Ada → How Ada Works
How Ada works
From `ada compile` to CLAUDE.md, agents, and hooks on disk. Four phases. No technical knowledge required.
Install and run
Ada runs in your terminal. No account required. No API key setup for first use. You run it in your project directory — Ada detects the codebase context automatically as part of the CTX stage.
If you're starting a new project with no existing code, that's fine too. Ada compiles from intent — the codebase context stage simply notes that the project is greenfield.
Elicitation — the questions that matter
Before Ada compiles, it runs structured elicitation. This is a focused dialogue session designed to surface the blocking unknowns — the things Ada genuinely doesn't know that would cause the wrong system to be built.
Ada asks semantic questions, not technical ones.
You described a "dashboard." Who sees it — the person who owns the data, or someone they grant access to?
The owner only. This is a private view. No sharing.
The data updates in real time, or on a schedule?
Daily. It's a digest — not a live view.
Each question corresponds to an unknown that would force an assumption in the compilation. Ada asks the minimum set of questions to resolve them — not everything, just what blocks the right output.
The questions surface: what the system should do, what it should not do, who uses it, what constraints are non-negotiable, what decisions are already made. You answer in plain language. Ada handles the rest.
7-stage compilation
Once elicitation is complete, Ada compiles. The pipeline runs automatically — you watch the stages pass.
Each stage reduces ambiguity in one dimension. CTX grounds the compilation in real codebase state. INT structures your answers into a formal intent graph. PER maps who uses the system and how that shapes decisions. ENT extracts the canonical domain entities. PRO synthesizes the state machines and workflows. SYN assembles all layers into the output artifacts. GOV evaluates coherence — and iterates if it doesn't pass.
The 0.94 coherence score means the compiled output closely traces back to the stated intent. The Governor does not approve until it passes threshold.
Files on disk — verify, then build
CLAUDE.md written agents/ 8 files written hooks/ pre-tool guards written Plain files. You read them before handing to Claude Code.
CLAUDE.md is the first thing to read. Does it match what you meant?
If yes: open Claude Code. It reads CLAUDE.md on every turn and builds
against what Ada wrote. If no: run ada compile again
with the correction — Ada's elicitation picks up where you diverged.
The agents and hooks run automatically — you don't need to configure them. Claude Code loads the relevant agent for each domain context. The hooks enforce constraints at every tool call, silently.
The session pattern: Ada compiles once. Claude Code builds for as many sessions as you need, always within the intent Ada encoded. When scope changes significantly: re-run Ada to update the artifacts.
Who this is for
Ada works at whatever level you think in. You don't need to know which database to use or which framework to pick. Ada infers technical choices from conceptual descriptions.
The only requirement: you need to know what the system should do. Not in technical terms — in behavioral ones. "When a user does X, Y should happen." "This is for people who need Z, not people who need W." "This is not a [category]."
That's the level Ada works at. Everything below it is Ada's to handle.
Full Ada documentation →git clone https://github.com/alexrozex/ada ~400 iterations since late 2024. Built by one person.
Full setup guide →