Introduction

Cordia is an intent-driven specification language for AI-assisted software development. You write VibeSpec (a .cordia file); the Bloom compiler turns it into deterministic Cordia Prompt JSON that any AI system can consume.

Cordia does not generate code — it generates intent. The same input always yields byte-identical JSON.

Installation

Install the CLI globally to get the bloom command:

npm install -g @cordiacode/cli
bloom compile app.cordia

Or run it without installing:

npx @cordiacode/cli compile app.cordia

Or use the compiler as a library:

npm install @cordiacode/core

VibeSpec language

VibeSpec is line-based: every non-empty line begins with one symbol that labels your intent. A spec needs exactly one goal in [ ]; everything else is optional. The compiler never guesses what a bare line means — each line says one thing.

[Todo App]

{
A simple personal todo tracker.
}

<React, TypeScript>
+ Add tasks
+ Mark tasks done
- No multi-user
=> code

The context block's { and } each go on their own line. Milestones nest + features inside a { } body.

@cordiacode/cli

The CLI exposes the bloom command for compiling .cordia files locally.

bloom compile  hello.cordia              # print Cordia Prompt JSON to stdout
bloom compilef hello.cordia              # write hello.json next to the spec
bloom compilef hello.cordia -o out.json  # choose the output path
bloom compile  hello.cordia -w           # recompile on save

Invalid specs print line-numbered diagnostics and write nothing.

@cordiacode/core

The compiler engine: lexer → parser → validator → Prompt compiler. Use it inside apps, web services, or scripts when you want compilation without shelling out to the CLI.

npm install @cordiacode/core

Compile source to deterministic Cordia Prompt JSON:

import { analyze, compileToJson } from '@cordiacode/core';

const { spec, errors } = analyze(source);
if (errors.length === 0) {
  const json = compileToJson(spec); // deterministic Cordia Prompt JSON
}

analyze(source) returns the parsed AST plus diagnostics (in lexer → parser → validator order).compileToJson(spec) serializes to canonical JSON text; compile(spec) returns the object. Each diagnostic is a CordiaError with code, message, line, and column.

@cordiacode/schema

Defines the Cordia Prompt JSON shape and its TypeScript types. Use it to type or validate generated prompt objects before storing, exporting, or handing them to another AI layer.

npm install @cordiacode/schema

import type { CordiaPrompt } from '@cordiacode/schema';

const prompt: CordiaPrompt = compile(spec);

Cordia Prompt JSON

Every compile produces six top-level sections in a fixed order — metadata, project, implementation, validation, deliverables, execution. Empty sections are omitted, and output is byte-for-byte deterministic.

{
  "metadata": { "language": "Cordia", "version": "Dichotoma-1.0" },
  "project": {
    "goal": "Todo App",
    "context": ["A simple personal todo tracker."]
  },
  "implementation": {
    "stack": ["React", "TypeScript"],
    "features": ["Add tasks", "Mark tasks done"],
    "exclusions": ["No multi-user"]
  },
  "deliverables": { "outputs": ["code"] }
}

This JSON is the contract every layer below the compiler depends on — including the Alliodora colony, which routes it to roles and runs it. Try the compiler live on the home page.