cotlib: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

cotlib is a Go library for creating, validating, and working with Cursor-on-Target (CoT) events. CoT is an XML-based protocol used for situational awareness, originally developed by MITRE and extended by TAK (Team Awareness Kit) applications.

Build and Test Commands

# Build the library (requires CGO for libxml2-based schema validation)
go build ./...

# Build without schema validation (no CGO required)
go build -tags novalidator ./...

# Run all tests
go test -v ./...

# Run tests for a specific package
go test -v ./cottypes
go test -v ./validator

# Run a single test
go test -v -run TestEventCreation ./...

# Run benchmarks
go test -bench=. ./...

# Regenerate type catalog (after modifying XML type definitions)
go generate ./cottypes

# Format code before committing
gofmt -s -w $(git ls-files '*.go')

# Run security scanner
go install github.com/securego/gosec/v2/cmd/gosec@latest && gosec -no-fail ./...

Architecture

Core Package (cotlib)

The main package in cotlib.go provides:

• Event struct: The primary data structure representing a CoT message with XML marshaling/unmarshaling
• NewEvent(), NewPresenceEvent(): Event constructors
• EventBuilder: Fluent API for constructing events with NewEventBuilder().WithContact().WithGroup().Build()
• UnmarshalXMLEvent(): Parses XML into Event with security limits and validation
• ValidateType(), ValidateHow(), ValidateRelation(): Validation functions for CoT type codes
• Event pooling via getEvent()/ReleaseEvent() for reduced allocations

Subpackages

• cottypes/: Type catalog system with ~10k CoT type definitions
  • Catalog: Thread-safe registry with zero-allocation lookups
  • generated_types.go: Auto-generated from CoTtypes.xml (MITRE) and TAKtypes.xml (TAK extensions)
  • GetCatalog(): Returns the singleton catalog instance
  • How/relation value mappings for position source and relationship types