Add Makefile and README.md

Author: stringintech

Makefile

@@ -0,0 +1,37 @@
+.PHONY: all build test test-single clean
+
+all: build test
+
+build:
+	@echo "Building orchestrator binary..."
+	mkdir -p bin
+	cd orchestrator && go build -o ./bin/orchestrator
+	@echo "Building go-handler binary..."
+	cd go-handler/go-bitcoinkernel && $(MAKE) build-kernel && $(MAKE) build
+	cd go-handler && go build -o ./bin/go-handler
+	@echo "Building rust-handler binary..."
+	cd rust-handler && cargo build --release
+	@echo "Build complete!"
+
+test:
+	@echo "Running all conformance tests with go-handler..."
+	-./orchestrator/bin/orchestrator -handler ./go-handler/bin/go-handler -testdir testdata
+	@echo "Running all conformance tests with rust-handler..."
+	-./orchestrator/bin/orchestrator -handler ./rust-handler/target/release/rust-handler -testdir testdata
+
+test-single:
+	@if [ -z "$(TEST)" ]; then \
+		echo "Error: TEST variable not set. Usage: make test-single TEST=testdata/chainstate_basic.json"; \
+		exit 1; \
+	fi
+	@echo "Running test with go-handler: $(TEST)"
+	./bin/orchestrator -handler ./go-handle/bin/go-handler -testfile $(TEST)
+	@echo "Running test with rust-handler: $(TEST)"
+	./bin/orchestrator -handler ./rust-handler/target/release/rust-handler -testfile $(TEST)
+
+clean:
+	@echo "Cleaning build artifacts..."
+	cd go-handler/go-bitcoinkernel && $(MAKE) clean
+	cd orchestrator && go clean && rm -rf build
+	cd go-handler && go clean && rm -rf build
+	cd rust-handler && cargo clean

README.md

@@ -0,0 +1,67 @@
+# Bitcoin Kernel Binding Conformance Tests
+
+This directory contains a language-agnostic conformance testing framework for Bitcoin Kernel bindings.
+
+## ⚠️ Work in Progress
+
+## Overview
+
+The framework ensures that all language bindings (Go, Python, Rust, etc.) behave identically by:
+- Defining a standard JSON protocol for testing
+- Providing shared test cases that work across all bindings
+- Enforcing consistent error handling and categorization
+
+## Architecture
+
+```
+┌─────────────┐         ┌──────────────────┐
+│ Orchestrator│────────▶│  Handler Binary  │
+│  (Go Test   │ stdin   │  (Go/Rust/etc)   │
+│   Runner)   │◀────────│                  │
+└─────────────┘ stdout  └──────────────────┘
+       │                         │
+       │                         │
+       ▼                         ▼
+  ┌─────────┐            ┌────────────────┐
+  │ Test    │            │ Binding API    │
+  │ Cases   │            └────────────────┘
+  │ (JSON)  │            
+  └─────────┘
+```
+
+1. [**Orchestrator**](./orchestrator): Spawns handler binary, sends test requests, validates responses
+2. **Handler Binary**: Implements protocol, calls binding API, returns results
+   - [Go handler](./go-handler) for the [Go binding](https://github.com/stringintech/go-bitcoinkernel)
+   - [Rust handler](./rust-handler) for the [Rust binding](https://github.com/TheCharlatan/rust-bitcoinkernel)
+3. [**Test Cases**](./testdata): JSON files defining requests and expected responses
+
+## Getting Started
+
+### Cloning
+
+Clone the repository with submodules:
+
+```bash
+git clone --recurse-submodules https://github.com/stringintech/kernel-bindings-spec.git
+```
+**Note:** go-handler currently depends on go-bitcoinkernel via a submodule.
+
+
+### Building
+
+Use the provided Makefile to build the project:
+
+```bash
+# Build everything!
+make build
+```
+
+### Running Tests
+
+```bash
+# Run all conformance tests with both Go and Rust handlers
+make test
+
+# Run a specific test file with both Go and Rust handlers
+make test-single TEST=testdata/chainstate_basic.json
+```