A Unified Vocabulary for Intent-Based Development

Intent-based development represents a shift in how we build software: rather than focusing on code as the source of truth, developers define structured intent — describing what they want the system to do.

To support consistent understanding and collaboration, this guide introduces a standardized vocabulary for the core components of intent-based development.

Core Concepts

Intent-Based Development

A programming model where software is generated from structured declarations of desired outcomes. Developers express what they want through intent files, and implementation is treated as an output rather than a source of truth.

Intent File

A structured YAML file that describes a single software feature, component, or behavior.

Content may include:

• Natural language requirements (e.g., “a login form with email and password”)
• Structured props, types, or routes
• Builder reference indicating how to interpret the file

Format: .intent.yaml Example filename: LoginForm.intent.yaml

Intent files are version-controlled and serve as the primary design artifact in an intent-based system.

Builder

A module that transforms an intent file into one or more artifacts. Builders:

• Define the expected schema of the intent file
• Encapsulate domain expertise and implementation conventions
• Produce output files (e.g., components, tests, endpoints)

Builders may also output new intent files — enabling recursive, compositional generation. This nesting supports the structured creation of large systems through a tree of progressively lower-level intents.

Examples:

• react/component
• sql/report-query
• nextjs/page

Artifact

The result of applying a builder to an intent file. Artifacts may include:

• Code (e.g., .tsx, .sql, .ts)
• Tests
• Configuration files
• Documentation

Artifacts are derivable and often ephemeral. They can be regenerated at any time and are typically reviewed before being committed. They are not considered authoritative sources of system design — the intent is.

Concern

A modular file defining reusable logic or behavior that applies across multiple intent files. Concerns are used to express cross-cutting functionality such as:

• Authentication
• Theming
• Analytics
• Accessibility

Format: .concern.yaml

Intent files reference concerns to inherit behavior declaratively without duplicating implementation logic.

Agent

An interface that assists the developer in interacting with the system. Agents can:

• Help author or refine intent files
• Select builders
• Orchestrate multi-step workflows
• Execute generation commands

Agents may be implemented as:

• CLI tools
• IDE plugins
• Conversational UIs

Agents are facilitators — they do not generate code themselves but coordinate the use of builders based on developer input.

Project

A cohesive collection of intent files, concerns, and generated artifacts organized around a shared software purpose.

Projects may:

• Contain both generated and hand-written code
• Use different builders for different subsystems
• Employ recursive generation patterns for hierarchical structure
• Define organization-specific conventions through builder composition

Diffing and Regeneration

Because artifacts are not the source of truth, the system enables:

• Diffing: Previewing generated changes before applying them
• Regeneration: Reapplying builders after edits to intent files
• Override policies: Manually edited files can be protected, merged, or liberated from further generation

These mechanics ensure developer control and traceability without undermining the declarative model.

Conclusion

Intent-based development allows developers to move up the abstraction ladder — focusing on what they want rather than how to implement it. But to scale, this approach requires precise and consistent terminology.

This vocabulary provides the foundation for communicating about, building with, and extending Declary. As the toolkit evolves, these core concepts will remain central to how intent and implementation interact in future software systems.