The specification language that talks back
Allium clarifies your intent into a precise, durable artefact that keeps your AI grounded, conversation after conversation.
rule OrderConfirmed {
when: CheckoutCompleted(cart, payment)
requires: cart.items.all(in_stock)
requires: payment.authorised
ensures:
let order = Order.created(
items: cart.items,
total: cart.total
)
PaymentCaptured(order: order)
}OrderConfirmed triggers PaymentCaptured, which charges the customer immediately. A backorder would charge before the item ships. Should we defer payment capture until the item is available, or capture immediately and refund if we can't fulfil?
orders.allium. BackorderPlaced authorises payment and defers capture until ReadyToFulfil. Implementing now.
A formal language for what a system should do, separate from how.
There are four reasons to capture intent this way.
Stops the drift
Within a session, meaning slips: by prompt twenty, the model is pattern-matching its own outputs rather than your original intent. A spec anchors it.
Persists between sessions
Constraints and decisions captured in conversation disappear when the chat ends. An Allium spec is a durable artefact the next session, or the next engineer, can read.
Surfaces contradictions
Markdown lets two requirements quietly disagree. Allium's structure exposes the conflict instead of letting a capable model paper over it.
Separates what from how
Code can't tell you whether a behaviour is intended. Allium says what the system should do; the code says how it does it. The gap between them is information.
Why not just point the LLM at the code?
Modern LLMs navigate codebases effectively, and many engineers find this sufficient. The limit appears when you need to distinguish what the code does from what it should do.
Code captures implementation, including bugs and expedient decisions, and the model treats all of it as intended behaviour. Precise prompting helps, but precise prompting is specifying intent: which behaviours are deliberate, which constraints must be preserved.
You end up writing descriptions of intent scattered across your prompts. Allium captures it in a form that persists, so the next engineer, the next model, or you next week can read not just what the system does, but what it was meant to do.
def confirm_order(cart, payment):
# expedient: VIP carts skip the stock check
if cart.vip or all(i.in_stock for i in cart.items):
capture(payment) # charges immediately
return Order.created(cart)rule OrderConfirmed {
when: CheckoutCompleted(cart, payment)
requires: cart.items.all(in_stock)
requires: payment.authorised
ensures: PaymentCaptured(order)
}Why not capture requirements in markdown?
Markdown gives you no framework for surfacing ambiguities and contradictions. You can require authentication in one section and allow guest checkout in another, and the format never flags the tension. A capable model may resolve it silently in a way you didn’t intend; a weaker one may never notice it exists.
## Authentication
- users must be authenticated to check out
## Checkout
- guest checkout is supportedrule Checkout {
when: CheckoutStarted(session)
requires: session.authenticated
}
rule GuestCheckout {
when: CheckoutStarted(session)
requires: not session.authenticated
}Checkout and GuestCheckout share trigger CheckoutStarted
requires: session.authenticated · requires: not session.authenticated → preconditions can never both hold
The model doesn’t need to be clever enough to spot the issue in prose — the structure does that work. Markdown can capture robust behaviour with enough diligence, but that diligence falls entirely on the author. Allium’s constraints guide you toward completeness and consistency.
The specification and the code evolve together.
Refining a behavioural model alongside implementation deepens your understanding of both the problem and your solution. LLMs generate code from descriptions, shifting where design thinking happens — the specification becomes the site of that thinking, and the code its expression.
What you meant the system to do — goals, constraints, the behaviour you actually intended.
The durable artefact both directions meet in — the shared site where design thinking now lives.
What the code actually does today, including behaviours that were never explicitly decided.
Elicitation works forward from intent through structured conversation; distillation works backward from implementation. Distillation reveals what you built; elicitation clarifies what you meant. When the two diverge, you’ve found something worth investigating.
Redundancy isn’t duplication, it’s resilience.
A common objection: a behavioural model beside the code violates single-source-of-truth. But code captures both intentional and accidental behaviour, with no mechanism to tell them apart — is that authentication quirk a feature or a bug? The code can’t tell you. You need something outside the code to even say “this is wrong.” Engineers already accept this elsewhere.
Type systems
Express intent the implementation must satisfy. Nobody calls a signature a duplicate of its body.
Tests
Assert expected behaviour against actual behaviour. The gap between them is the whole point.
Allium
The same pattern, raised to behaviour: a model of what, and under which conditions, beside the code that says how.
When code and model disagree, that disagreement is information.