What this looks like in practice
Type /allium in Claude Code and Allium examines your project, then offers to distill from existing code or build a new spec through conversation.
auth/. I can see login, password reset, session management and role-based access. I've drafted an initial spec at auth.allium with 4 entities and 9 rules. A few things I want to flag:
auth/login.py:34 allows unlimited retries for users with an internal role. Is that intentional, or should the lockout policy apply to everyone?
The elicitation guide and distillation guide cover both approaches in detail.
Allium surfaces implications you missed
A customer’s account was suspended for a terms of service violation. They’ve appealed and the team wants to let them back in.
user.status = active for password resets. This user's status is suspended, so the reset is blocked by design. Reactivating through password reset would bypass your AccountReinstated rule, which requires admin approval and logs an audit trail.
AccountReinstatedViaAppeal rule that combines both steps with the audit trail intact?
Without Allium, the LLM would have relaxed the status check, accidentally creating a backdoor around an admin control. The behavioural model caught that password reset and account reinstatement are separate concerns with different approval requirements.
Knowledge persists across sessions
A developer starts a new session days later, working on a different feature.
SubscriptionCreated ensures a payment is processed and InvoiceGenerated requires invoice.amount > 0. A free first month would need to bypass both.
PaymentMethod still be captured upfront, or only when the trial converts?
The developer never mentioned invoicing or payment method capture. The Allium did, from a session that ended days ago. Without it, the LLM would have implemented the trial with no awareness of these constraints, and the gaps would have surfaced in production.
Allium grounds a design conversation
A developer asks for a straightforward feature.
AdminAction requires the admin's scope to include the target resource. The current scopes are billing, users and support. Should this endpoint require billing scope?
billing to the support role, but that also grants access to refunds and plan changes, which your Allium controls through the same scope.
billing into billing.read and billing.write. Support gets read-only access, finance gets both. Your code in admin/permissions.py already distinguishes read and write operations but maps them both to the same scope check, so the implementation is halfway there.
Without Allium, the LLM would likely have implemented a simple is_admin check. Instead, the conversation surfaced a scoping model, explored its implications for a second team, and arrived at a design that aligns the behavioural model with a distinction the code already made but never formalised.
Distillation catches drift
A developer asks the LLM to check whether the code still matches the Allium.
LoginAttempt requires user.failed_attempts < max_login_attempts, with a default of 5. But auth/login.py line 47 hardcodes the limit at 3 and doesn't reset the counter after a successful login. The Allium says UserAuthenticates ensures user.failed_attempts = 0.
Code and intent diverge silently over time. Allium gives the LLM something to check against, turning “does this look right?” into a concrete comparison with a definitive answer. See the distillation guide for a structured approach to catching drift, and the elicitation guide for building specs from conversations like the ones above.