.boa Format Reference

The human-readable, AI-friendly manifest format used throughout BOA.

BOA uses .boa files instead of JSON for all manifests. The format is line-based, keyword-driven, and designed to be readable by both humans and AI. Each file type serves a specific purpose — block definitions, workflow orchestration, block registration, and project overview.

Why not JSON? JSON is noisy for manifests — braces, quotes, commas. The .boa format is flat, scannable, and diff-friendly. AI models parse it with fewer tokens, and humans read it without squinting.

block.boa — Block Manifest

Every block has a block.boa file that declares its name, version, inputs, outputs, business rules, and test fixtures. This is the single source of truth for the block's contract.

Keyword Required Description Example
BLOCK Yes Block name and version BLOCK Add 1.0.0
LAYER Yes Block layer: primitive, capability, domain, workflow, interface, ui-block, ui-capability LAYER domain
RUNTIME Yes Runtime environment: node, python, js, wasm RUNTIME node
ENTRY Yes Entry point file ENTRY index.js
DESC Yes One-line description DESC Adds two numbers.
INTENT Recommended User's original requirement in their words INTENT User needs to add numbers.
RULE Recommended Business rule or constraint (repeatable) RULE Both inputs must be numbers.
TAGS Recommended Comma-separated keywords for discovery TAGS math, arithmetic
IN Yes Input field (! = required, ? = optional) IN amount:number!
OUT Yes Output field with type OUT result:number
FIXTURE Recommended Test case: input JSON -> expected output JSON FIXTURE {"a":3} -> {"result":3}
MOCK For capabilities Mock response for capability/side-effect blocks MOCK {"id":1} -> {"data":{...}}
ERR Optional Error type name the block may throw ERR ValidationError
DEPS Optional Block dependency (name@version) DEPS OtherBlock@1.0.0

Complete block.boa Example

BLOCK CalculateOrderValue 1.0.0
LAYER domain
RUNTIME node
ENTRY index.js
DESC Computes subtotal from order items.
INTENT Calculate the total value of a shopping cart.

RULE subtotal = sum of (price * quantity) for each item.
RULE Round to 2 decimal places.
RULE Return 0 if items array is empty.

TAGS orders, pricing, cart, math

IN items:array!
OUT subtotal:number

FIXTURE {"items":[{"price":50,"quantity":2}]} -> {"subtotal":100}
FIXTURE {"items":[]} -> {"subtotal":0}

ERR ValidationError
DEPS Add@1.0.0
One file, everything you need A single block.boa declares the contract, business rules, test cases, and metadata. No separate test files, no schema files, no configuration sprawl.

workflow.boa — Workflow Manifest

Workflows chain blocks together declaratively. Each step references a block by name and version, maps inputs from previous steps or the initial input, and can include conditionals, error handlers, and parallel execution.

Keyword Description Example
WORKFLOW Workflow name and version WORKFLOW OrderFlow 1.0.0
DESC One-line description DESC Process an order.
CONFIG Key-value configuration CONFIG currency = "USD"
ON_ERROR Error handler block ON_ERROR handleError@1.0.0
STEP Step declaration (stepId = Block@version) STEP calcValue = CalcValue@1.0.0
MAP Input mapping (indented under STEP) MAP field <- source.field
WHEN Conditional execution (indented under STEP) WHEN $steps.prev.output.count > 3
SUB Sub-workflow call (indented under STEP) SUB SubWorkflowName
PARALLEL Start parallel execution group PARALLEL
END_PARALLEL End parallel execution group END_PARALLEL

Complete workflow.boa Example

WORKFLOW OrderProcessing 1.0.0
DESC Calculate value, apply tax, and format the order summary.
CONFIG currency = "USD"
ON_ERROR handleOrderError@1.0.0

# Calculate the cart subtotal
STEP calcValue = CalculateOrderValue@1.0.0
  MAP items <- _initial.items

# Fetch tax rates and compute tax (runs in parallel)
PARALLEL
  STEP calcTax = ComputeTax@1.0.0
    MAP subtotal <- calcValue.subtotal
    MAP jurisdiction <- _initial.region

  STEP fetchDiscount = LookupDiscount@1.0.0
    MAP couponCode <- _initial.coupon
END_PARALLEL

# Apply discount only if one was found
STEP applyDiscount = ApplyDiscount@1.0.0
  MAP subtotal <- calcValue.subtotal
  MAP discount <- fetchDiscount.discount
  WHEN $steps.fetchDiscount.output.discount > 0

# Format the final order summary
STEP format = FormatString@1.0.0
  MAP template <- _initial.template
  MAP total <- calcTax.total
MAP source references Use _initial.field to reference the workflow's initial input. Use stepId.field to reference a previous step's output. The engine resolves these at runtime.

blocks.boa — Block Registry

The block registry is a flat file that maps every block in a project to its directory. One line per block, using the format:

# Format: Name version -> path/to/block

Add 1.0.0 -> src/Primitives/Math/Add
Multiply 1.0.0 -> src/Primitives/Math/Multiply
FormatString 1.0.0 -> src/Primitives/String/FormatString
CalculateOrderValue 1.0.0 -> src/DomainBlocks/Orders/CalculateOrderValue
ComputeTax 1.0.0 -> src/DomainBlocks/Orders/ComputeTax
fetchCart 1.0.0 -> src/UICapabilities/Cart/fetchCart

The CLI uses this file to locate blocks when running boa test, boa run, and boa impact. Every block must be registered here to be discoverable.

Keep it sorted Group blocks by layer or domain for readability. The framework reads the file line-by-line and does not require any specific ordering, but a sorted registry is easier to scan.

project.boa — Project Overview

The project file is the top-level manifest that gives a bird's-eye view of the entire project. It lists domains, the blocks in each domain, and the workflows that chain them. AI reads this file first to build a mental model before touching any code.

Keyword Description Example
PROJECT Project name and version PROJECT MyProject 1.0.0
DESC Project description DESC E-commerce order system.
DOMAIN Domain grouping (indented block list below) DOMAIN Orders
FLOW Workflow summary showing block chain FLOW OrderProcessing: A -> B -> C

Complete project.boa Example

PROJECT MyProject 1.0.0
DESC E-commerce order processing system.

DOMAIN Orders
  CalculateOrderValue: Computes subtotal from items
  ComputeTax: Calculates tax based on jurisdiction
  ApplyDiscount: Applies coupon discounts to subtotal

DOMAIN Formatting
  FormatString: Formats output strings with templates

DOMAIN Math
  Add: Adds two numbers
  Multiply: Multiplies two numbers

FLOW OrderProcessing: CalculateOrderValue -> ComputeTax -> FormatString
FLOW QuickCalc: Add -> Multiply
Read this first, every session When an AI (or a developer) opens a BOA project, project.boa provides the full mental model in a single file — what domains exist, what blocks belong to each, and how workflows connect them.

Field Types

The IN and OUT keywords declare typed fields. BOA supports the following types for block inputs and outputs:

Type Description
string Text value
number Numeric value (integer or floating point)
boolean true or false
object JSON object (nested key-value pairs)
array JSON array (ordered list of values)
any Any type (use sparingly)

Field Modifiers

Append a modifier to the type to indicate whether a field is required or optional:

# Required field (! modifier)
IN amount:number!

# Optional field (? modifier)
IN couponCode:string?

# Default is required (no modifier = required)
IN items:array
Be explicit Always use ! or ? to make intent clear. While the default is required, an explicit ! removes any ambiguity for both humans and AI.

AI-Native Keywords

Four keywords in block.boa are specifically designed for AI-assisted development. They preserve context across sessions and make blocks self-documenting.

INTENT

Captures the user's original requirement in their own words. When an AI revisits a block months later, INTENT tells it why the block exists — not just what it does.

INTENT User wants to calculate the
total price of items in a cart.

RULE

Declares business rules as structured, one-per-line statements. AI can parse, validate, and enforce these rules without reading the implementation code.

RULE subtotal = sum of price * qty.
RULE Round to 2 decimal places.
RULE Return 0 for empty arrays.

FIXTURE

Inline test cases that make every block self-testing. No separate test files, no test framework. Run boa test or boa validate to verify all fixtures.

FIXTURE {"a":3,"b":5}
  -> {"result":8}

TAGS

Comma-separated semantic keywords that enable AI to discover relevant blocks. Instead of grepping code, AI searches tags to find reusable blocks.

TAGS orders, pricing, cart,
     e-commerce, math
Always include these four keywords Every block.boa should have INTENT, at least one RULE, at least one FIXTURE, and a TAGS line. Together they make blocks discoverable, self-documenting, and self-testing — the foundation of AI-native development.