alexander-let/brex

Purpose and Entry Points

Brex is a Rust workspace implementing a compilable instruction language for AI coding agents. A .brex project specification compiles into a typed IR, Markdown task prompts, JSON artifacts, and enforcement policy. Main user entry points are the CLI binary at crates/brex-cli/src/main.rs and language-server binary at crates/brex-lsp/src/main.rs. Source specs, templates, and reusable packs live in examples/, templates/, and std/.

1. CLI Orchestration

brex-cli owns command dispatch for project lifecycle operations: initialization, parsing/checking, builds and artifact emission, introspection, formatting/diffing, policy hooks, drift, and doctor workflows.

• crates/brex-cli/src/main.rs

• crates/brex-cli/src/intent.rs

• crates/brex-cli/src/hooks.rs

It is the principal boundary between filesystem-oriented user commands and the compiler/codegen crates.

2. Language Front End

The syntax crate defines Brex’s source model, lexical analysis, parsing, source spans, AST, and formatter. It transforms .brex text into AST-level structures while retaining diagnostics/source location context.

• crates/brex-syntax/src/lexer.rs

• crates/brex-syntax/src/parser.rs

• crates/brex-syntax/src/ast.rs

A separate Tree-sitter grammar supports editor ecosystem integration rather than the compiler’s core parser.

• tree-sitter-brex/grammar.js

3. Semantic Compilation and Loading

Semantic analysis resolves imports/namespaces, validates and expands the parsed specification, and performs substitution before producing compiler-ready meaning. This is where local specs connect to standard packs or imported Brex files.

• crates/brex-sema/src/lib.rs

• crates/brex-sema/src/load.rs

• crates/brex-sema/src/subst.rs

Inputs can incorporate the repository’s standard instruction packs such as std/security.brex, std/rust_api.brex, and std/frontend.brex.

4. Intermediate Representation Contract

brex-ir defines the normalized, shared IR passed from semantic compilation to all output producers. This is the central architectural contract: code generators should consume IR rather than source syntax or CLI-specific state.

• crates/brex-ir/src/lib.rs

The expected deliverables demonstrate this boundary: project.ir.json and project.policy.json under tests/golden/simple/expected/.

5. Artifact Generation

Two backend crates render the IR into downstream-agent consumable formats. The JSON backend emits machine-readable IR, schema, and policy; the Markdown backend emits project/task prompt files and derives graph, score, and diff-oriented views.

• crates/brex-codegen-json/src/lib.rs

• crates/brex-codegen-md/src/lib.rs

• crates/brex-codegen-md/src/graph.rs

The main build flow is: .brex source → syntax AST → semantic resolution → IR → selected ir, md, policy, and/or schema outputs.

6. Agent Workflow and Policy Boundaries

Brex turns roles, rules, goals, files, tasks, and write constraints into prompts and policies. CLI intent and hook modules provide the operational boundary for executing/replaying task workflows and enforcing policy around agent actions.

• crates/brex-cli/src/intent.rs

• crates/brex-cli/src/hooks.rs

• examples/policy-hook/guard-write.sh

Generated prompt organization is task-centric, with project manifests and task/adversary/review prompts represented in golden outputs such as tests/golden/shop-api/expected/prompts/.

7. Developer Integrations and Delivery

The repository targets native Rust binaries distributed through Cargo and GitHub Releases. The LSP exposes language functionality to editors; Tree-sitter supplies grammar support. GitHub Actions run CI, release, drift, and living-diff workflows.

• crates/brex-lsp/src/main.rs

• .github/workflows/release.yml

• .github/workflows/brex-drift.yml

No web runtime or server-side external service is indicated; persistent state and products are source files plus generated filesystem artifacts.