From 1552c7fc6698c4e0bc0b331a8aafdcabc4a55741 Mon Sep 17 00:00:00 2001
From: Ben Vincent <ben@unkin.net>
Date: Thu, 11 Jun 2026 22:24:52 +1000
Subject: [PATCH] Add kind quickstart guide

---
 hack/kind/README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 hack/kind/README.md

diff --git a/hack/kind/README.md b/hack/kind/README.md
new file mode 100644
index 0000000..300defc
--- /dev/null
+++ b/hack/kind/README.md
@@ -0,0 +1,105 @@
+# Forgebot Kind Quickstart
+
+Run forgebot end-to-end in a local [kind](https://kind.sigs.k8s.io/) cluster.
+
+## Prerequisites
+
+- Docker
+- kind v0.31+
+- kubectl
+
+## Setup
+
+```bash
+# Use a separate kubeconfig so your existing context is untouched
+export KUBECONFIG=/tmp/forgebot-kind.kubeconfig
+
+# Create cluster
+kind create cluster --name forgebot
+
+# Build and load images
+cd /path/to/forgebot
+docker build -t forgebot-api:dev -f Dockerfile.api .
+docker build -t forgebot-operator:dev -f Dockerfile.operator .
+kind load docker-image forgebot-api:dev --name forgebot
+kind load docker-image forgebot-operator:dev --name forgebot
+
+# Install CRDs
+kubectl apply -f config/crd/bases/
+
+# Deploy everything (postgres, RBAC, API, operator, sample CRs)
+kubectl apply -f hack/kind/manifests/
+
+# Wait for pods
+kubectl -n forgebot wait --for=condition=ready pod -l app=postgres --timeout=60s
+kubectl -n forgebot wait --for=condition=ready pod -l app=forgebot-api --timeout=60s
+kubectl -n forgebot wait --for=condition=ready pod -l app=forgebot-operator --timeout=60s
+```
+
+## Test
+
+```bash
+# Port-forward the API (use a non-default port to avoid conflicts)
+kubectl -n forgebot port-forward svc/forgebot-api 18000:8000 &
+
+# Health check
+curl -s http://localhost:18000/health
+# {"status":"ok"}
+
+# Simulate a Gitea webhook (issue comment with /plan command)
+curl -s -X POST http://localhost:18000/api/v1/webhook/gitea \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "created",
+    "comment": {
+      "id": 1,
+      "body": "/plan implement auth",
+      "user": {"login": "unkinben"}
+    },
+    "issue": {"number": 42},
+    "repository": {
+      "full_name": "unkin/test-repo",
+      "default_branch": "main"
+    }
+  }'
+
+# Verify the task was queued
+curl -s http://localhost:18000/api/v1/tasks | python3 -m json.tool
+
+# Check that the operator created an AgentTask and a Job
+kubectl -n forgebot get agenttasks
+kubectl -n forgebot get jobs
+
+# Operator logs
+kubectl -n forgebot logs -l app=forgebot-operator --tail=20
+```
+
+### Expected output
+
+```
+NAME            COMMAND   REPO              PHASE       AGE
+task-e611a7c7   plan      unkin/test-repo   Succeeded   9s
+```
+
+The operator polls the API for pending tasks, creates an `AgentTask` CR, which triggers a K8s Job. The test pool uses `busybox:latest` so the Job completes immediately.
+
+## Create a task via the API (agent subtask spawning)
+
+```bash
+curl -s -X POST http://localhost:18000/api/v1/tasks \
+  -H "Content-Type: application/json" \
+  -d '{
+    "command": "implement",
+    "repository": "unkin/terraform-vault",
+    "ref": "main",
+    "body": "Add K8s auth role for new-service",
+    "author": "unkinben"
+  }' | python3 -m json.tool
+```
+
+## Teardown
+
+```bash
+kind delete cluster --name forgebot
+rm -f /tmp/forgebot-kind.kubeconfig
+```