hush: 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

HushSpec is agentic compliance as code: a portable, open specification for declaring, enforcing, and proving the security controls an AI agent operates under. 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
├── library/           # Vertical policy library, embedded as builtins
├── fixtures/          # Test fixtures (valid/invalid documents, edge cases)
├── generated/         # Cross-SDK contract data the generators consume
├── scripts/           # Generators and checks CI runs with --check
└── 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