What are Custom Context items?
Custom Context items are short knowledge documents you write to capture the things LLMs can't know about your project: naming conventions, architecture decisions, preferred APIs, design system tokens, security constraints.
Each item is a markdown file stored in your project's
.dalia/context/ directory. It has a name, a set of
tags for categorization, a markdown body with the actual knowledge,
and an auto-generated summary.
---
name: "SASS Variables and Conventions"
summary: "Enforces use of SASS design token variables..."
tags:
- drupal-frontend-engineer
- css
- theming
---
Use the SASS variables defined in
`web/themes/custom/mytheme/scss/_variables.scss`.
Never use hardcoded color values — always reference
the design token variables.Tags are free-text. Dalia suggests existing tags from your task files so teams naturally converge on a shared vocabulary. The summary is auto-generated by Claude Haiku, keeping the overhead of creating items low.
How they work with RAG
Custom Context items integrate through the same Retrieval-Augmented Generation pipeline that powers Dalia's Drupal knowledge. The difference: Drupal docs are provided by Dalia. Custom Context is provided by you.
When you start a generation, Dalia searches your context index for items semantically relevant to the current task. Matching items are injected into agent prompts during the specification chat and planning phases. For code execution, relevant context is pre-baked directly into each task file so agents read it alongside their instructions.
This means your conventions influence every phase — from the first clarifying question the AI asks, through the architecture plan, all the way to the code it writes.
Benefits
- Project-specific knowledge
- Embed your team's conventions, preferred patterns, and architecture decisions without modifying Dalia itself. The AI learns how your project works.
- Automatic relevance
- Semantic search surfaces the right context items based on what you're building. You don't manually select which items apply — the embedding model handles matching.
- Full pipeline coverage
- Context items influence spec conversations, planning, and code execution. Your conventions aren't just suggestions — they're woven into every phase.
- Audit trail
- Dalia logs which context items matched for each generation, with similarity scores. You can see exactly what knowledge influenced the AI's decisions.
- Low friction
- Auto-generated summaries, tag autocomplete from existing tasks, and a simple markdown format keep the cost of creating items minimal.
Trade-offs to consider
- Requires RAG
- Custom Context depends on the RAG system being enabled and the embedding model downloaded (~33 MB, one-time). Without RAG, context files still exist on disk but won't be searched or injected.
- Manual curation
- You create and maintain context items yourself. There's no automatic extraction from your codebase. This is by design — the value comes from intentional, curated knowledge — but it does require upfront effort.
- Token budget
- Injected context items consume tokens in agent prompts. For most projects this is negligible, but teams with many large context items should monitor whether key information is being crowded out.
- No mid-execution requests
- Agents can't dynamically request additional context during execution. Items are resolved at the start of each phase. If a relevant item doesn't surface automatically, it won't be available mid-task.
What to put in Custom Context
The best context items capture knowledge that's specific to your project and not derivable from the code alone. Some examples:
- Coding standards — naming conventions, file organization rules, preferred design patterns
- API documentation — endpoint schemas, authentication patterns, data model relationships
- Design system — SASS variables, component guidelines, theme documentation, breakpoint conventions
- Architecture decisions — why you chose certain approaches, what not to use, deprecated patterns
- Business rules — validation requirements, security constraints, compliance considerations
- Team preferences — "favor SDCs over custom theme hooks", "use JSON:API instead of custom controllers"
Short, focused items work better than long documents. One convention per item gives the embedding model a clearer signal for matching.