humanlayer · allisoneer · Mar 23, 2025 · Mar 22, 2025 · Mar 22, 2025 · Mar 22, 2025
@@ -76,8 +76,8 @@ You can run these commands directly in the ts directory or use the pattern-match
 - `make lint-fix`: Run golangci-lint and fix issues
 - `make test`: Run unit tests
 - `make test-e2e`: Run end-to-end tests (requires a running Kind cluster)
-- `make manifests`: Generate Kubernetes manifests (CRDs, RBAC)
-- `make generate`: Generate Go code (DeepCopy methods)
+- `make manifests`: Generate Kubernetes manifests (CRDs, RBAC) - **Important:** Run this after modifying CRD types or controller RBAC annotations
+- `make generate`: Generate Go code (DeepCopy methods) - **Important:** Run this after adding new struct fields
 
 #### Build Commands
 - `make build`: Build the manager binary
@@ -122,6 +122,14 @@ Individual components can be managed separately:
 - `make tempo-up/down`
 - `make loki-up/down`
 
+## Documentation
+
+The project includes detailed documentation in the `/kubechain/docs/` directory:
+
+- [MCP Server Guide](/kubechain/docs/mcp-server.md) - Working with Model Control Protocol servers
+- [CRD Reference](/kubechain/docs/crd-reference.md) - Complete reference for all Custom Resource Definitions
+- [Kubebuilder Guide](/kubechain/docs/kubebuilder-guide.md) - How to develop with Kubebuilder in this project
+
 ## Typical Workflow
 
 ### Local Development with Kind Cluster
@@ -168,6 +176,16 @@ Alternatively, clean up components individually:
 - Test with Ginkgo/Gomega framework
 - Document public functions with godoc
 
+### Kubebuilder and CRD Development
+- All resources should be in the `kubechain.humanlayer.dev` API group
+- Use proper kubebuilder annotations for validation and RBAC
+- Add RBAC annotations to all controllers to generate proper permissions
+- Run `make manifests` after modifying CRD types or controller annotations
+- Run `make generate` after adding new struct fields to generate DeepCopy methods
+- When creating new resources, use `kubebuilder create api --group kubechain --version v1alpha1 --kind YourResource --namespaced true --resource true --controller true`
+- Ensure the PROJECT file contains entries for all resources before running `make manifests`
+- Follow the detailed guidance in the [Kubebuilder Guide](/kubechain/docs/kubebuilder-guide.md)
+
 ### TypeScript
 - Use 2-space indentation
 - No semicolons (per prettier config)

@@ -17,4 +17,67 @@ resources:
   kind: LLM
   path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
   version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: Tool
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: Agent
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: Task
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: TaskRun
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: TaskRunToolCall
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: MCPServer
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: humanlayer.dev
+  group: kubechain
+  kind: ContactChannel
+  path: github.com/humanlayer/smallchain/kubechain/api/v1alpha1
+  version: v1alpha1
 version: "3"
@@ -113,16 +113,38 @@ previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml
 is manually re-applied afterwards.
 
 ## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
 
-**NOTE:** Run `make help` for more information on all potential `make` targets
+### Development Workflow
 
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
+The project uses [Kubebuilder](https://book.kubebuilder.io/) for scaffolding Kubernetes resources and controllers. If you're extending the API or adding new resource types, please refer to our [Kubebuilder Guide](./docs/kubebuilder-guide.md) for detailed instructions on:
+
+- Adding new custom resources
+- Updating existing resources
+- Working with controllers
+- Generating RBAC permissions
+- Following best practices
+
+### Make Targets
+
+Run `make help` for more information on all potential `make` targets. Common targets include:
+
+- `make build` - Build the manager binary
+- `make manifests` - Generate WebhookConfiguration, ClusterRole, and CustomResourceDefinition objects
+- `make generate` - Generate code (DeepCopy methods)
+- `make test` - Run tests
+- `make docker-build` - Build the Docker image
+
+### Resources
+
+- [Kubebuilder Book](https://book.kubebuilder.io/introduction.html) - Official Kubebuilder documentation
+- [Controller Runtime](https://github.com/kubernetes-sigs/controller-runtime) - Library for building controllers
+- [Kubernetes API Conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) - Standards for Kubernetes API design
 
 ## Documentation
 
 - [MCP Server Guide](./docs/mcp-server.md) - Detailed guide for working with MCP servers
 - [CRD Reference](./docs/crd-reference.md) - Complete reference for all Custom Resource Definitions
+- [Kubebuilder Guide](./docs/kubebuilder-guide.md) - How to develop with Kubebuilder in this project
 
 ## Resource Types
 

@@ -0,0 +1,64 @@
+/*
+Copyright 2025 the Kubechain Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
+// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
+
+// ContactChannelSpec defines the desired state of ContactChannel.
+type ContactChannelSpec struct {
+	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// Foo is an example field of ContactChannel. Edit contactchannel_types.go to remove/update
+	Foo string `json:"foo,omitempty"`
+}
+
+// ContactChannelStatus defines the observed state of ContactChannel.
+type ContactChannelStatus struct {
+	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+
+// ContactChannel is the Schema for the contactchannels API.
+type ContactChannel struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   ContactChannelSpec   `json:"spec,omitempty"`
+	Status ContactChannelStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// ContactChannelList contains a list of ContactChannel.
+type ContactChannelList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []ContactChannel `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&ContactChannel{}, &ContactChannelList{})
+}
@@ -0,0 +1,54 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.17.1
+  name: contactchannels.kubechain.humanlayer.dev
+spec:
+  group: kubechain.humanlayer.dev
+  names:
+    kind: ContactChannel
+    listKind: ContactChannelList
+    plural: contactchannels
+    singular: contactchannel
+  scope: Namespaced
+  versions:
+  - name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: ContactChannel is the Schema for the contactchannels API.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: ContactChannelSpec defines the desired state of ContactChannel.
+            properties:
+              foo:
+                description: Foo is an example field of ContactChannel. Edit contactchannel_types.go
+                  to remove/update
+                type: string
+            type: object
+          status:
+            description: ContactChannelStatus defines the observed state of ContactChannel.
+            type: object
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}
@@ -9,6 +9,7 @@ resources:
 - bases/kubechain.humanlayer.dev_taskruns.yaml
 - bases/kubechain.humanlayer.dev_taskruntoolcalls.yaml
 - bases/kubechain.humanlayer.dev_mcpservers.yaml
+- bases/kubechain.humanlayer.dev_contactchannels.yaml
 # +kubebuilder:scaffold:crdkustomizeresource
 
 patches: