From haira
Assists Haira compiler development covering lexer, parser, resolver, checker, Go codegen pipeline, runtime library, AST design, and diagnostics. For features, bugs, architecture.
How this skill is triggered — by the user, by Claude, or both
Slash command
/haira:haira-compilerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```
Source (.haira) -> Lexer -> Parser -> Resolver -> Checker -> Codegen -> go build -> Binary
No AI phase in the compiler. All LLM interaction happens at runtime through agent method calls.
compiler/
main.go # CLI entry: build, run, parse, check, lex, emit, lsp
go.mod # Go 1.22, zero external dependencies
internal/
token/token.go # TokenKind constants, Token struct
lexer/lexer.go # Hand-written scanner
ast/ast.go # AST nodes (Go interfaces as sum types), Span, Spanned[T]
parser/parser.go # Recursive descent + Pratt expression parsing
resolver/resolver.go # Multi-file import resolution
checker/checker.go # Type checking + semantic analysis (2 passes)
codegen/
codegen.go # 8-pass emission orchestrator
emitter.go # Low-level Go source emitter (buffer + indent)
expressions.go # Expression-to-Go conversion
statements.go # Statement emission
agentic.go # Provider/tool/agent/workflow emission
stdlib.go # Standard library function mapping
types.go # Haira-type-to-Go-type conversion
project.go # Temp project setup + go build invocation
driver/driver.go # Pipeline orchestrator
errors/errors.go # Diagnostic system (Diagnostic, PrettyPrint)
formatter/ # Source code formatter
lsp/ # Language server protocol
manifest/ # package.haira handling
runtime/
runtime.go # go:embed bundle.tar.gz
embedded/haira/*.go.src # Runtime source files (renamed to avoid compilation)
| Package | Can Import |
|---|---|
token | (none) |
ast | (none) |
lexer | token |
parser | token, ast |
resolver | ast |
checker | ast, token, errors |
codegen | ast, token |
errors | ast |
driver | all above |
lsp | driver, ast, checker, errors |
Hand-written scanner. Converts UTF-8 source to token stream.
Key token kinds:
Provider, Tool, Agent, WorkflowFn, Struct, Enum, Type, Import, Export, From, Pub, If, Else, For, While, Match, Return, Break, Continue, True, False, Nil, And, Or, Not, In, Spawn, Select, Try, Catch, Defer, Step, Test, Assert, ConstPlus, Minus, Star, Slash, Percent, Eq, EqEq, Ne, Lt, Gt, Le, Ge, PipeArrow, Amp, Caret, Tilde, Shl, Shr, Pipe, Arrow, FatArrow, DotDot, DotDotEq, Dot, Question, At, EllipsisInt, Float, String, InterpolatedString, TripleQuoteStringSpecial handling:
${expr} interpolation: nested brace depth tracking"""...""" triple-quoted strings: auto-dedenting/* /* nested */ */ block comments1_000_0000xFF, 0b1010, 0o77Recursive descent for declarations/statements + Pratt (precedence-climbing) for expressions.
Top-level declarations:
TypeDef — struct with typed fieldsEnumDef — enum with variantsTypeAlias — type Name = TypeFunctionDef — regular functionsMethodDef — Type.method() with implicit selfImportDecl — 4 import formsExportDecl — export { ... }ProviderDecl — provider blocksToolDecl — tool functions with descriptionAgentDecl — agent configuration blocksWorkflowDecl — workflow with optional decorator triggerTestDecl — test "name" { ... }Expressions (27 types):
Literals, identifiers, binary/unary ops, calls, method calls, field access, indexing, pipe, lambda, match, if-expressions, lists, maps, struct instances, ranges, error propagation (?), orelse, some/none, spawn, select, async.
Statements (14 types): Assignment, let/const, if/else, for-in, while, return, try/catch, defer/errdefer, match, break/continue, step, assert, expr statements.
Patterns (6 types):
Wildcard (_), literal, identifier, constructor, or-pattern (A | B), range (1..5).
orelse|> (pipe)or / || (logical OR)and / && (logical AND)| (bitwise OR)^ (bitwise XOR)& (bitwise AND)==, !=<, >, <=, >=, .., ..=<<, >>+, -*, /, %-, not, ~ (unary)(), [], ., ? (postfix)Every node carries a Span:
type Expr struct {
Node ExprNode
Span Span // Required for error reporting
}
type Span struct {
Start int // byte offset
End int
}
Go interfaces serve as sum types:
type ExprNode interface { exprKind() }
type StmtNode interface { stmtKind() }
Multi-file module resolution:
pub items and agentic declarations visibleProgram with merged items in dependency orderResolution order:
Two-pass type checking:
self bindingmodel, api_key, backend, host, temperature, max_tokens, transport, command, args, url, endpoint, env, headers, input_token_cost, output_token_cost, api_versionprovider field (or model), validate tool references exist, check handoff targets exist, warn on unknown fieldsPrimitive: int, float, string, bool, any, void, error
Compound: [T] (list), {K: V} (map)
Named: struct, enum
Function: (T, U) -> V
Generic types are parse-accepted but erased to any in v1.
var Claude = &haira.Provider{...}haira.ToolDef varshaira.WorkflowDef varsvar declarationsmain()Agents with handoffs must be initialized after their handoff targets:
// If FrontDesk.handoffs = [BillingAgent, TechAgent]
// Init order: BillingAgent -> TechAgent -> FrontDesk
Compiler generates JSON schema from Haira types:
| Haira Type | JSON Schema |
|---|---|
int | "integer" |
float | "number" |
bool | "boolean" |
string | "string" |
[]T | "array" with items |
| struct | "object" with properties |
-> stream) generate both:
StreamHandler — SSE endpointHandler — JSON fallback endpoint@webui generates form UI registrationCodegen scans generated Go code to determine imports:
fmt — string interpolation, print callsencoding/json — JSON marshal/unmarshalsync — spawn blocks (WaitGroup)haira — runtime library (always needed for agentic code)go.modbundle.tar.gz) -> haira/ packagemain.gogo build -o <output> to produce binaryPrimitive (primitive/haira/): Core runtime — always included
Stdlib (stdlib/): External integrations — tree-shaken at compile time
See references/runtime.md for detailed runtime file listing.
func init() {
RegisterStoreBackend("postgres", func(dsn string) Store { /* ... */ })
}
1. make bundle-runtime -> copies primitive/ + stdlib/ to staging
2. UI SDK built (bun build) and included
3. All archived as bundle.tar.gz
4. Embedded via go:embed in compiler binary
5. At compile time: extract -> write main.go -> go build
errors.Diagnostic{
Level: errors.Error, // Error, Warning, Info
Message: "type mismatch",
Span: node.Span,
File: filename,
Hint: "expected int, got string",
}
haira build [file] [-o output] # Compile to native binary
haira run [file] # Compile and execute
haira check [file] # Type-check only
haira emit [file] # Show generated Go code
haira test [file] # Run test blocks
haira fmt [file] # Format source
haira parse [file] # Show AST
haira lex [file] # Show tokens
haira init # Create package.haira
haira lsp # Start language server (stdio)
haira version # Show version
internal/token/token.go — Add TokenKind (if new keyword)internal/lexer/ — Add keyword recognitioninternal/ast/ast.go — Define node struct with Span, add marker methodinternal/parser/ — Implement parsing ruleinternal/checker/ — Add type checkinginternal/codegen/ — Add Go code generationmake dev — Verify all passesprimitive/haira/<module>.go — Runtime implementationinternal/codegen/stdlib.go — Map qualified names in resolveQualified()internal/codegen/stdlib.go — Register in IsStdlibImport()internal/codegen/expressions.go — Add return type in orelseReturnType() if neededexamples/make dev && make build-examplesinternal/codegen/agentic.goprimitive/haira/make ci.hairaai keyword backmake build # Build compiler
make test # Run tests
make dev # fmt + vet + test
make ci # vet + test + build-examples
make build-examples # Compile all .haira examples
make install # Install to $GOPATH/bin
npx claudepluginhub mrzdevcore/haira --plugin hairaThis skill should be used when the user asks about Compact language mechanics, syntax reference, types (Field, Bytes, Uint, Boolean, Opaque, Vector, Maybe, Either, enums, structs), type casting with "as", operators, arithmetic, control flow, for loops, modules, imports, include, pragma, stdlib functions (persistentHash, transientHash, disclose, assert, pad, default), map and fold operations, or Compact compiler errors and wrong syntax patterns.
Designs multi-agent harness architectures for long-running AI apps using Generator-Evaluator pattern, Sprint Contract negotiation, and context management. Use for agent orchestration, quality evaluation loops, and complex full-stack AI development.