Butter

An implementation-agnostic intent specification language for AI agents. Write .butter files, compile them to structured prompts, and provide the desired implementation context separately.

Butter makes application intent explicit: what software should do, what must remain true, which inputs are acceptable, and what outcomes are expected. It does not prescribe a programming language, framework, database, or UI technology. The AI agent receives the compiled specification together with the implementation context and produces an implementation for review and testing.

Why Butter

Natural language prompts can be vague, while data files describe data rather than intent. Butter sits in between: compact enough to write by hand and structured enough to make important requirements easier to communicate and review.

Actions run in order. Steps inside a feature are declared sequentially, making the intended order explicit.
Parameters are typed. Inputs use declared types such as string, integer, boolean, and enum.
Constraints are explicit. enforce expressions sit under the actions they qualify and state conditions that must hold.
One specification, many stacks. Butter describes application intent independently of the implementation language, framework, database, or UI technology.
Zero dependencies. The compiler is a single Go binary with no third-party packages.

Installation

From Source

Requires Go 1.21+.

git clone https://github.com/lebohang0824/butter.git butter
cd butter
go build -o butter main.go

Then install it with the install script below.

Install Script

# Linux / macOS
chmod +x install.sh
./install.sh            # compiler + VS Code extension
./install.sh binary     # compiler only
./install.sh extension  # extension only

# Windows PowerShell
.\install.ps1
.\install.ps1 -Command binary
.\install.ps1 -Command extension

Verify

butter --version
# butter v2.1.0

Quick Start

Create a file called hello.butter:

app HelloWorld
  description "A simple demonstration"
  version "1.0.0"

feature Greet
  params
    name string

  actions
    "Say hello to the user"

Compile it:

butter compile hello.butter

This produces hello.prompt.md — a Markdown prompt ready to paste into an AI chat:

# [SYSTEM SPEC] HelloWorld
> **Version:** 1.0.0
> **Description:** A simple demonstration

## Feature: Greet

### Params
* `name` (string)

### Execution Sequence
**CRITICAL:** Execute the following steps strictly in order. Do not
proceed to the next step until the current one is complete.

1. **Say hello to the user**

Need the specs in another format? Use the -f flag:

butter compile hello.butter -f json   # produces hello.json
butter compile hello.butter -f yaml   # produces hello.yaml

AI Workflow

This is where Butter pays off.

Write a .butter spec — declare features, parameters, and sequential actions.
Compile with butter compile spec.butter — this produces spec.prompt.md.

Paste the prompt into your AI chat with a short instruction:

Implementation context:
- Use the selected language, framework, and project conventions

Butter specification:
[paste compiled spec.prompt.md here]

Implement the application intent. Keep actions in listed order and respect
all types, rules, enforce expressions, and interface contracts.

The AI uses the specification and implementation context to produce an implementation for review and testing.

The spec defines what to build. The AI figures out how.

Syntax Overview

File Structure

Every .butter file starts with an app declaration, followed by zero or more feature or endpoint blocks. Blocks are defined by strict 2-space indentation per nesting depth.

app MyApp
  description "What the app does"
  version "1.0.0"

  rules
    "Users may only access resources they own"
    "Operations that create duplicate records must be rejected"

feature FeatureName
  description "What this feature does"
  version "1.0.0"

  params
    name type

  actions
    "Do something"

endpoint EndpointName "route/path"
  description "What this endpoint does"
  method "POST"

  params
    name type

  actions
    "Do something"

  returns
    200 "OK"

Keywords

Keyword	Where	What it does
`app`	Top level	Root of the spec. Every file starts with this.
`feature`	Under app	A discrete capability — a module or sub-system.
`endpoint`	Under app	An HTTP API contract — route, method, params, responses, actions, returns.
`description`	Anywhere	A quoted context string.
`version`	Anywhere	A version identifier.
`rules`	Under app	App-wide application intent, business constraints, and invariants.
`params`	Under feature/endpoint	Typed input parameters.
`actions`	Under feature/endpoint	Sequential execution steps (quoted strings).
`enforce`	Under action	A constraint that must hold for the action to succeed.
`responses`	Under endpoint	Named response schemas with typed fields.
`returns`	Under endpoint	Maps HTTP status codes to responses or strings.

Types

Type	Example
`string`	`name string`
`integer`	`count integer`
`double`	`amount double`
`boolean`	`active boolean`
`enum[...]`	`priority enum["low", "high"]`
`array[...]`	`tags array[string]`

Comments

# This is a comment
app MyApp  # inline comments work too

Full Example

See a complete todo app in the Language Guide, or browse the spec files in the specs/ directory.