CRAFT 🍺 — C++-Rooted AI-First Transpiler

CRAFT is a thin, unambiguous wrapper language designed from the ground up for LLMs and AI agents to generate, verify, and debug code — while transpiling 1:1 to clean, high-performance C++20 with zero runtime overhead.

Traditional languages optimize for human writers.
CRAFT optimizes for machines that now write most code.

Vision

CRAFT enforces a single canonical way to express every construct ("One Way Only"), embeds contracts (@prove) and mandatory runtime shadow tests (@test) directly into the grammar, maps explicitly to C++ RAII memory semantics, and provides verified escape hatches (cpp { }) for unsafe operations.

It prioritizes low token entropy and predictability so LLMs produce correct, deterministic code on the first pass.

A built-in --human mode produces annotated pseudo-C++ with inline comments explaining contracts, ownership semantics, error propagation (?), and trace instrumentation — making AI-generated code easy for humans to review without learning CRAFT syntax.

Key Features

• Machine-first design: Unambiguous grammar with exactly one way to do everything
• Mandatory contracts & tests: @prove and @test are part of the syntax — untested code is invalid
• Safe by default: Raw pointers and unsafe ops require explicit cpp { } escape
• Zero-cost abstractions: own<T> → std::unique_ptr, ref<T> → const T&, Result<T,E> → std::expected
• Verified C++ interop: extern from "header" checked with libclang
• First-class debugging: @trace structured logs + #line directives for GDB/LLDB
• Human bridge: --human mode generates richly annotated pseudo-C++ for easy review
• Proven with evaluation: A/B testing shows generated CRAFT achieves 100% correctness and test coverage versus 85% correctness for raw C++.

Full locked principles → PRINCIPLES.md

Grammar & Examples

CRAFT has a tiny, context-free grammar (24 EBNF rules, 0 ambiguous parses).

• Full grammar and lexical rules → GRAMMAR.md
• Curated examples with grammar coverage → GRAMMAR.md
• Full, ready-to-use example files → examples/ directory

Human Review Bridge (--human mode)

LLM generates CRAFT → craft transpile --human produces annotated C++ with:

• Contract explanations (@prove)
• Ownership transfer notes
• ? error propagation paths
• Trace instrumentation markers
• Source line mapping

See HUMAN_BRIDGE.md for details and the recommended review workflow. See EVALUATION.md for A/B test results showing CRAFT's generated correctness and test coverage gains.

Transpiler

The transpiler implementation lives in transpiler/ and includes parser, codegen prototype, and validation tests.

• transpiler/README.md documents the current parser/codegen approach.
• transpiler/test_e2e.py, transpiler/test_lexer.py, and transpiler/test_parser.py exercise the engine.
• The current focus is evolving the C++ codegen prototype from the locked CRAFT grammar.

Quick Start

1. Read MEMORY.md, PRINCIPLES.md, and GRAMMAR.md.
2. Use TRANSLATE_PROMPT.md for C++ → CRAFT translation.
3. Follow one training round from TRAINING_LOOP.md and run cleanup:
   • Windows: ./cleanup.ps1
   • macOS/Linux: ./cleanup.sh
4. Sanity-check examples/, seeds/cpp/, transpiler/, and dataset/.
5. Open a PR with a short summary of what changed and why, using .github/PULL_REQUEST_TEMPLATE.md.

Contributor Workflow

Recommended end-to-end flow for contributors and developers:

1. Read core docs:
   • PRINCIPLES.md
   • GRAMMAR.md
   • MEMORY.md
2. Run one training round process from TRAINING_LOOP.md and produce/update training_round*.json.
3. Run cleanup to normalize artifacts:
   • Windows: ./cleanup.ps1
   • macOS/Linux: ./cleanup.sh
4. Review outputs:
   • dataset/ for canonical extracted corpora
   • seeds/cpp/ for high-quality start points
   • examples/ for showcase CRAFT examples
   • transpiler/ for parser and codegen validation
   • TODO.md for unresolved follow-ups
5. Commit changes on a branch and open a pull request.

Current Status (May 2026)

• Phase 1 Complete: Vision, principles, grammar, human bridge, and translation tools locked.
• A/B evaluation validated: EVALUATION.md reports 100% correctness and 100% test coverage for generated CRAFT versus 85% correctness and 0% tests for raw C++.
• Round 4 Complete: Grammar stable with 0 gaps in 50-problem test set. Stdlib finalized (Vec.sort, Set.remove, Map.remove, abs).
• Transpiler prototype active: handlers generics, enums, match, ? propagation, @trace, --human mode, and OOP (impl blocks with member functions). See transpiler/README.md.

See v2-roadmap.md for deferred features (structured concurrency, auto-generated bindings, C++23 opt-in).

This is an early-stage passion project 🍺 exploring better tools for AI-generated systems code.

Project Structure

CRAFT/

• Docs — core design, grammar, reference, evaluation, workflow, and roadmap
• transpiler/ — parser and C++ codegen prototype with validation tests
• dataset/ — canonical raw C++ corpus, translated CRAFT corpus, and human-readable notes
• examples/ and seeds/cpp/ — polished showcase examples and high-quality C++ seeds
• training_data/ — active refinement rounds and completed archive
• cleanup.ps1, cleanup.sh, cleanup.md — artifact cleanup and normalization

Contributing

Contributions are very welcome! Especially helpful right now:

• More C++ → CRAFT translation examples
• Feedback on grammar clarity and LLM generation quality
• Early parser or codegen help (Tree-sitter, Lark, Rust, etc.)
• Ideas for improving the --human decompiler

Please read the locked documents (PRINCIPLES.md and GRAMMAR.md) before proposing changes so we stay aligned with the machine-first philosophy.

Use .github/PULL_REQUEST_TEMPLATE.md for the PR checklist and contribution guidance.

---

Created: April 2026 | Last updated: May 31, 2026
CRAFT — Because AI deserves a better language to write in. 🍺