Skip to content

CLAUDE.md

Latest commit

 

History

History
212 lines (170 loc) · 9.57 KB

CLAUDE.md

File metadata and controls

212 lines (170 loc) · 9.57 KB
Raw

QVAC — Agent Context

Setup (New Developers)

After cloning, run /setup to configure your agent tooling:

/setup all      # Configure both Claude Code and Cursor
/setup claude   # Configure Claude Code only
/setup cursor   # Configure Cursor only

This copies shared config (conduct rules, knowledge docs, agents, skills) from packages/ocr-ggml/.agent/ into .claude/ and .cursor/. Re-run anytime after pulling changes to packages/ocr-ggml/.agent/.

CRITICAL: Never Skip Tests

NEVER delete, disable, skip, or weaken existing tests. Fix the code or the test. If you cannot fix it, report on Asana and STOP. No exceptions.

CRITICAL: Bash Command Rules

These rules are mandatory. Violating them blocks the automated pipeline.

  • NEVER use heredocs (<< EOF), cat >, or echo > to write files — use the Write tool instead
  • NEVER use $() command substitution in bash — write to a temp file instead (e.g. git commit -F /tmp/msg.txt). For $(nproc), query nproc first then hardcode the value (e.g. make -j12)
  • NEVER chain commands with &&, ||, or ; — make separate Bash tool calls. Use flags like git -C <path> instead of cd <path> && git ...
  • NEVER use pipes (|) or redirects (2>&1, 2>/dev/null) — use dedicated tools or separate calls
  • ALWAYS use dedicated tools: Write instead of cat >, Read instead of cat, Grep instead of grep, Glob instead of find, Edit instead of sed

Overview

QVAC (Quantum Versatile AI Compute) is a monorepo for building local-first, P2P AI applications. Cross-platform support for Node.js, Bare runtime, and Expo.

Build & Test — Quick Reference

Native Addons (C++ packages, e.g. llm-llamacpp)

Prerequisites: clang-22, libc++-22-dev, libc++abi-22-dev, vcpkg, bare >=1.24, bare-make

The CI workflows install LLVM via .github/actions/setup-llvm, which is the single source of truth for the LLVM major used across the monorepo. To bump the LLVM version everywhere, change version (and windows-version for the chocolatey pin) in that one action file. Local dev environments should match the CI default (clang-22 today); if you're temporarily blocked on an older system clang you can override the vcpkg toolchain locally — every package's linux-clang.cmake now uses unversioned clang/clang++, so pointing them at a different version only requires update-alternatives on your machine.

cd packages/<addon-package>
npm install                # install JS + native dependencies
bare-make generate         # generate CMake build files (downloads vcpkg deps)
bare-make build            # compile C++ addon
bare-make install          # install .bare prebuild to prebuilds/

Full one-liner: npm install && bare-make generate && bare-make build && bare-make install

Testing:

npm run test               # run all integration tests (brittle framework)
npm run test:integration   # same as above (generates all.js then runs bare test/integration/all.js)
npm run test:cpp           # C++ unit tests (GoogleTest)
npm run coverage:cpp       # C++ code coverage (llvm-cov)
bare test/integration/<name>.test.js  # run a single integration test

Linting:

npx standard <file>        # JS lint (standardjs)
npm run lint               # lint all JS (excludes addon/)

SDK (packages/qvac-sdk)

cd packages/qvac-sdk
bun install
bun run build       # lint + typecheck + compile
bun run lint        # eslint + typecheck
bun run format      # prettier check

Testing:

bun run test:unit
bun run test:bare
bun run test:security
bun run test:security:bare

Environment Variables

Required tokens (see .env.example):

  • GH_TOKEN — GitHub PAT for qvac-registry-vcpkg access
  • HF_TOKEN — HuggingFace token for model license verification
  • NPM_TOKEN — npm token for @qvac scoped packages

CI Pipeline

  • 85+ GitHub Actions workflows in .github/workflows/
  • Path-scoped: only affected packages build/publish
  • PR workflows: on-pr-*.yml — sanity checks, C++ linting, tests
  • Expensive tests gated behind verify label on PRs
  • Prebuild workflows: prebuilds-*.yml — multi-platform native bindings
  • Publishing: main → dev builds (GitHub Packages), release-* → npm

Repository Structure

qvac/
├── CLAUDE.md                  # This file
├── packages/
│   ├── ocr-ggml/
│   │   ├── .agent/                # Shared agent config (canonical source)
│   │   │   ├── README.md          # Framework documentation
│   │   │   ├── conduct.md         # Behavioral rules
│   │   │   ├── agents/            # Agent definitions (implementer, reviewer, etc.)
│   │   │   ├── knowledge/         # Domain knowledge docs
│   │   │   ├── skills/            # New skills (orchestrate, release, ci-validate)
│   │   │   ├── settings.json      # Canonical settings (permission allowlist)
│   │   │   ├── mcp.json           # Shared MCP server definitions
│   │   │   └── setup.sh           # Setup script (configures .claude/ or .cursor/)
├── .claude/                   # Claude Code config (generated by /setup)
│   ├── skills/setup/          # Bootstrap skill (tracked in git)
│   ├── agents/                # [GENERATED] from packages/ocr-ggml/.agent/agents/
│   ├── knowledge/             # [GENERATED] from packages/ocr-ggml/.agent/knowledge/
│   ├── agent-conduct.md       # [GENERATED] from packages/ocr-ggml/.agent/conduct.md
│   └── settings.json          # [GENERATED] from packages/ocr-ggml/.agent/settings.json
├── .cursor/                   # Cursor config
│   ├── skills/setup/          # Bootstrap skill (tracked in git)
│   ├── skills/                # Custom skills (qv-addon-*, qv-sdk-*, qv-pr-*, etc.)
│   ├── commands/              # Existing commands
│   └── rules/                 # .mdc files with Cursor-specific rules
│   ├── sdk/              # Main SDK entry point
│   ├── cli/              # CLI tool
│   ├── rag/          # RAG library
│   ├── infer-*/      # Inference addons (LLM, TTS, OCR, etc.)
│   ├── dl-*/         # Data loaders (filesystem, hyperdrive)
│   ├── logging/      # Logging
│   ├── error-base/   # Error handling base
│   ├── registry-server/ # Distributed model registry
│   └── docs/                  # Documentation
├── scripts/                   # Build and validation scripts
├── .github/workflows/         # CI/CD (85+ workflow files)
└── gitflow.md                 # Git workflow documentation

Code Conventions

Commit Message Format

prefix[tags]?: subject

Prefixes: feat, fix, doc, test, chore, infra, mod Tags: [api] (non-breaking), [bc] (breaking), [mod] (model changes), [notask] (PR), [skiplog]

Examples:

  • feat: add RAG support for LanceDB
  • fix[api]: fix completion stream error handling

PR Title Format

TICKET prefix[tags]: subject

Example: QVAC-123 feat[api]: add new endpoint

TypeScript/SDK Rules

  • Use function declarations, not arrow functions (unless necessary)
  • Always use @ aliases for imports, never relative paths
  • No any or unknown unless absolutely necessary
  • No return type annotations on function definitions
  • Composition over classes (exception: error classes extending QvacErrorBase)
  • Co-locate Zod schemas with code; lowercase names, uppercase inferred types
  • Strict error handling: always use structured error classes, preserve cause

C++ Rules

  • clang-tidy for linting
  • CMake-based builds with vcpkg
  • GoogleTest for unit tests

Git Workflow

  • Fork-first model — contributors work in forks
  • main — development main, publishes dev builds
  • release-<package>-<x.y.z> — release lines, publishes to npm
  • feature-* / tmp-* — shared dev streams (GitHub Packages)

Agent Conduct

See packages/ocr-ggml/.agent/conduct.md for behavioral rules that all agents must follow (canonical source). Generated copy is placed in .claude/agent-conduct.md by /setup.

Knowledge Base

Domain-specific reference docs in packages/ocr-ggml/.agent/knowledge/ (copied to .claude/knowledge/ by /setup). When a question relates to one of these topics, read the corresponding knowledge file before answering.

Topic When to read File
CI / GitHub Actions CI failures, workflow triggers, validation, publishing packages/ocr-ggml/.agent/knowledge/ci-validation.md
Self-hosted CI runners Manual Workspace Cleanup, working-directory: ., runner.environment, qvac-* labels docs/ci/SELF-HOSTED-RUNNERS.md
Merge Guard / required status checks Adding a new job/workflow that should gate merges, wiring it into qvac-merge-guard / validate-pr vs. registering a standalone required check docs/ci/MERGE-GUARD.md (actionable checklist: qv-merge-guard-wire skill)
vcpkg / native builds vcpkg deps, triplets, registries, CMake integration, build failures packages/ocr-ggml/.agent/knowledge/vcpkg-management.md
llama.cpp Android Cross-compiling llama.cpp, ADB deployment, Vulkan GPU, Android inference packages/ocr-ggml/.agent/knowledge/llama-cpp-android.md
Model registry Adding/updating models, registry format, vcpkg port config packages/ocr-ggml/.agent/knowledge/registry-models.md

These topics are also handled by specialized agents (ci-validator, model-registry-updater, llama-cpp-android-runner).

Never Commit

  • .npmrc files
  • .env files
  • node_modules/
  • Build artifacts