Compose-Lang — Summary

Compose-Lang is an LLM-assisted compiler that turns minimal architecture specification files (.compose) into production code. It introduces a three-keyword DSL (model, feature, guide) that acts as the source-of-truth for code generation, eliminating the drift between documentation and implementation by making architecture the code generator itself. The compose build CLI command drives a traditional compiler pipeline (Lexer → Parser → Semantic Analyzer → IR) and then delegates code generation to an LLM backend, producing framework-specific output for Next.js, React, Vue, and other targets. Reproducible builds are achieved via LLM response caching — the same .compose input always produces the same output as long as the cache is present. The project ships a VSCode extension for syntax highlighting and code intelligence, completing the IDE integration story.

Unlike seeds such as spec-kit or openspec — which layer workflow and artifact management on top of an existing coding agent — Compose-Lang replaces the agent's freeform prompt-to-code loop with a compiler abstraction: the human writes specs, the compiler decides what code to generate, and incremental export maps track which symbols changed so only affected files are regenerated. This positions it closest to openspec's "architecture-first" philosophy but differs architecturally: openspec manages delta documents consumed by a coding agent, while Compose-Lang is itself the code generator and does not delegate to an interactive agent session.

Compose-Lang — Overview

Origin

Compose-Lang was created by the darula-hpp GitHub organization, first published in late 2025. It is written in JavaScript/Node.js with an accompanying VSCode extension. The project targets multi-developer teams who need reproducible, version-controlled code generation from architecture specifications.

Philosophy

The core manifesto is that architecture IS the code generator — architecture cannot drift from reality because the same spec file that is committed to git is what produces the running application. The README states:

"Write architecture specs → LLM generates code → Version control both. Architecture IS the code generator (can't drift). Read 50-line .compose file instead of 50-file codebase."

The language is deliberately minimal: three keywords and plain English descriptions. The belief is that LLMs handle natural language better than complex DSLs, so extra syntax is waste.

Explicit Antipatterns

The README explicitly warns against using Compose-Lang for:

• Quick one-off scripts or prototypes (use Cursor/Copilot instead)
• Solo short-term projects
• Complex algorithmic logic
• Mission-critical systems (banking, healthcare, flight control)
• Edge-case-heavy domains where 100% control is needed

Target Use Cases

• Multi-developer teams maintaining apps over time
• CRUD apps, internal tools, MVPs
• Iterative development (adding features incrementally)
• Framework migrations (regenerate for new tech stack)
• Architecture documentation that cannot go stale

Known Limitations (self-documented)

• No automated drift detection between generated code and export symbols
• No model version pinning (LLM provider updates can break reproducibility)
• LLMs struggle with complex domain logic
• Sweet spot is ~10-20 guides per file; quality degrades beyond that
• Perfect determinism is not guaranteed (cache mitigates but doesn't eliminate)

Compose-Lang — Architecture

Distribution

• npm package with compose binary (via package.json#bin)
• Install: npm install + npm link (local development mode, no npm publish found)
• VSCode extension: shipped as .vsix file (compose-lang-0.1.0.vsix) in vscode-compose/

Required Runtime

• Node.js (exact version constraint not specified)
• LLM provider API key (supports OpenAI-compatible endpoints)

Repository Structure

compose-lang/
├── cli/
│   ├── index.js          # CLI entry point, routes to subcommands
│   └── commands/
│       ├── build.js      # Compile .compose to code
│       ├── dev.js        # Watch mode for development
│       ├── init.js       # Initialize new project
│       ├── project.js    # Project management
│       ├── run.js        # Run generated project
│       ├── clean.js      # Clean generated artifacts
│       └── eject.js      # Eject from Compose (export raw code)
├── compiler/             # Compiler pipeline (Lexer → Parser → Semantic Analyzer → IR)
├── language/             # Language definition and parser
├── language-server/      # LSP implementation for IDE support
├── vscode-compose/       # VSCode extension (.vsix)
├── examples/             # Example .compose projects
├── composedocs/          # Documentation
├── docs/                 # Additional docs
├── scripts/              # Build/tooling scripts
├── SYNTAX.md             # Language reference
├── ROADMAP.md            # Planned features
└── package.json          # `bin: { compose: ./cli/index.js }`

Compiler Pipeline

.compose files → Lexer → Parser → Semantic Analyzer → IR (Intermediate Representation)
                                                          ↓
                                               LLM Code Generation Backend
                                                          ↓
                                              Framework-specific output
                                              (Next.js, React, Vue, etc.)

Target AI Tools

• Any LLM provider with OpenAI-compatible API (the compiler calls the LLM directly)
• Not a Claude Code / Codex plugin — operates independently of agent harnesses
• The vscode-compose extension integrates with the VS Code IDE

Config Files

• jsconfig.json — JavaScript project config
• Project-level config files (specific paths not documented in public README)

Compose-Lang — Components

CLI Commands (7 subcommands)

Language Primitives (3 keywords)

Compiler Components

VSCode Extension

Export Maps

A key runtime component: export maps track all symbols defined in .compose files so the dev and build commands can determine which generated files need regeneration when a spec changes (incremental compilation).

LLM Cache

Response cache commits LLM outputs to git alongside .compose files. Same input + same cache = same output, enabling reproducible builds.

Scripts (count: varies)

Located in scripts/ directory — purpose is build tooling and test helpers; not Claude Code hooks.

Compose-Lang — Uniqueness

Differs from Seeds

Compose-Lang occupies a category none of the 11 seed frameworks inhabit: it is a DSL compiler that is itself the code generator, rather than an agent harness that augments an existing AI coding tool. Openspec is the closest conceptual relative — both treat a spec document as the canonical source of truth — but openspec produces delta documents that a human-driven coding agent applies, whereas Compose-Lang's compiler directly generates code by calling an LLM backend without a human agent session in the loop. Superpowers and BMAD-METHOD add behavioral Iron Laws to an interactive Claude Code session; Compose-Lang bypasses interactive sessions entirely. Taskmaster-AI manages task decomposition for agents; Compose-Lang manages code generation for compilers. The compose eject command is a distinctive escape hatch not present in any seed: it lets users abandon the framework without losing their codebase.

Positioning

Compose-Lang targets the "architecture-first" philosophy at a lower level of abstraction than other frameworks. Instead of telling an agent "here is what to build," it constructs the prompt from a typed IR and produces deterministic (cached) outputs. The v0.2.0 self-described limitations are honest: no drift detection, no model pinning, quality degrades past 20 guides. This is a research/early-product-stage framework, not production-hardened.

Observable Failure Modes

1. Cache invalidation: If the LLM provider updates their model, cached responses from the old model may be inconsistent with new regenerations, causing partial-codebase drift.
2. Guide overflow: Past ~20 guides per file, output quality degrades. No guardrail prevents writing more.
3. No validation step: The compiler generates code but has no mechanism to verify it compiles, passes tests, or matches the spec intent. The human must review all output.
4. Lock-in: Generated code tightly couples to the .compose spec. Significant refactoring of business logic requires rewriting guides and rebuilding.
5. Single-LLM bottleneck: All generation goes through one LLM call per feature; complex cross-feature dependencies may produce inconsistent code if the LLM context window doesn't include all relevant models.