hush CLAUDE.md

CLAUDE.md

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

Project Overview

HushSpec is a portable, open specification for declaring security rules at the tool boundary of AI agent runtimes. It defines what security rules an agent operates under, without prescribing how those rules are enforced. The spec is runtime-agnostic and can be consumed by any enforcement engine.

Design Philosophy: Fail-closed. Invalid documents must be rejected at parse time; ambiguous rules deny access.

Repo Structure

hush/
├── spec/              # Specification prose (versioned markdown)
├── schemas/           # JSON Schema definitions for HushSpec documents
├── crates/            # Rust reference implementation
│   ├── hushspec/      # Core library: parsing, validation, types
│   ├── hushspec-testkit/  # Test utilities and fixture runners
│   └── hushspec-cli/      # h2h CLI binary
├── packages/          # Language SDKs
│   ├── hushspec/      # TypeScript (@hushspec/core)
│   ├── python/        # Python (hushspec)
│   └── go/            # Go (hushspec)
├── rulesets/          # Example and built-in ruleset YAML files
├── fixtures/          # Test fixtures (valid/invalid documents, edge cases)
└── docs/              # Documentation source (mdBook)

Common Commands

Rust

# Build all crates
cargo build --workspace

# Run all tests
cargo test --workspace

# Single crate
cargo test -p hushspec

# Lint and format
cargo fmt --all
cargo clippy --workspace -- -D warnings

# Format check (CI)
cargo fmt --all -- --check

TypeScript

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Lint
npm run lint

Python

# Install with dev dependencies
pip install -e "packages/python[dev]"

# Run tests
pytest packages/python/tests

Go

# Run tests
cd packages/go && go test ./...

# Vet
cd packages/go && go vet ./...