# Development Setup

> **Status:** Draft v0.1  
> **Author:** @agent-cos

---

## Prerequisites

- **Go 1.22+** — `go version` should show go1.22 or later
- **kubectl** — configured with a cluster context (kind/minikube for local dev)
- **helm** — v3.x for chart deployment
- **controller-gen** — from `sigs.k8s.io/controller-tools`
- **kustomize** — built into `kubectl kustomize` or standalone v4+
- **Docker** — for building controller images
- **kind** or **minikube** — for local Kubernetes clusters
- **OpenClaw gateway** or compatible LLM API endpoint

## Quick Start

### 1. Clone the Repository

```bash
git clone https://os.scoble.me/forgejo/marcus/scobleclaw.git
cd scobleclaw/kubeclaw
```

### 2. Create a Local Cluster

```bash
kind create cluster --name kubeclaw-dev
```

Or use an existing cluster:

```bash
kubectl config get-contexts
```

### 3. Install CRDs

```bash
make install
```

This applies all CRD YAML manifests to the cluster.

### 4. Run the Controller Locally

```bash
# In one terminal:
make run

# The controller connects to the current kubecontext
# Logs show reconciliation of CRD events
```

### 5. Deploy an Agent

```bash
# Apply a Provider first (no real credentials in dev)
kubectl apply -f config/samples/sample-provider.yaml

# Apply an Agent
kubectl apply -f config/samples/sample-agent.yaml

# Watch the agent pod come up
kubectl get pods -n agents -w
```

## Project Commands

| Command | Description |
|---------|-------------|
| `make generate` | Generate CRD deep copy and client code |
| `make manifests` | Generate CRD YAML manifests from Go types |
| `make install` | Apply CRDs to cluster |
| `make uninstall` | Remove CRDs from cluster |
| `make run` | Run controller locally |
| `make test` | Run unit and integration tests |
| `make docker-build` | Build controller Docker image |
| `make docker-push` | Push controller image to registry |
| `make helm-package` | Package Helm chart |
| `make deploy` | Deploy controller via Helm |

## Testing

### Unit Tests

```bash
make test
```

Tests cover:
- Reconciler logic (mock K8s client)
- Judge verifier (mock LLM responses)
- Webhook validation
- CRD schema validation

### Integration Tests

```bash
# Requires a running cluster and controller
make test-integration
```

Uses envtest (controller-runtime's test environment) for in-process API server testing.

### End-to-End Tests

```bash
# Requires a full cluster with all components
make test-e2e
```

## Local Development Tips

### Watch Controller Logs

```bash
kubectl logs -n kubeclaw-system deployment/kubeclaw-controller -f
```

### Debug Agent Pods

```bash
# Check pod status
kubectl describe pod -n agents <agent-name>

# Check judge sidecar logs
kubectl logs -n agents <agent-pod> -c judge

# Check workflow executor logs
kubectl logs -n agents <agent-pod> -c workflow-executor
```

### Hot Reload

For rapid iteration on CRD handler logic without rebuilding Docker images:

```bash
make run  # Restart on ctrl+c and re-run after code changes
```

## Architecture Notes

- The controller uses `controller-runtime`'s builder pattern: `NewControllerManagedBy(mgr).For(&Agent{}).Owns(&corev1.Pod{})`
- CRD types are in `api/v1alpha1/`
- Reconcilers are in `internal/controller/`
- The judge is implemented as a gRPC or HTTP sidecar
- Workflow templates are validated server-side before agent creation