lbuild-impl

Implementation runtime for Liminal Spec build packs.

What This Is

lbuild-impl is the CLI and SDK runtime that executes implementation workflows from a Liminal Spec build pack.

A build pack is produced by the liminal-spec process. At its core, it contains:

• an epic: what should be built, with acceptance criteria and test conditions
• a tech design: how the implementation should be structured and verified
• a set of story files: bounded implementation units with their own AC/TC detail

lbuild-impl reads that pack, runs bounded implementation and verification operations through provider CLIs, returns structured result envelopes, and writes durable artifacts back into the pack.

In short:

liminal-spec creates the implementation blueprint
lbuild-impl executes the blueprint

This package is one piece of the broader Liminal Build platform. It is not the whole product or web application; it is the implementation engine that other tools, agents, scripts, and services can call.

Is This For You?

Use lbuild-impl when you have a Liminal Spec build pack and want repeatable, inspectable implementation workflows.

It is a good fit if:

• you are implementing from an epic, tech design, and story files generated by liminal-spec
• you want a stable CLI for running implementation and verification operations
• you want an SDK that exposes the same operations programmatically
• you need structured JSON envelopes and persisted artifacts for auditability
• you are integrating Liminal Build workflows into another app, agent harness, or automation layer

It is not the right starting point if:

• you just want an AI assistant to make a small code edit
• you do not have a spec pack yet
• you are looking for the Liminal Build web application
• you want to discover requirements through freeform coding rather than execute from a written spec

If you need to create the build pack first, start with liminal-spec.

Core Concepts

Spec pack: the authored implementation input bundle: epic, tech design, test plan, and story files.

Run state: implementation-run files layered beside the authored pack, including impl-run.config.json, team-impl-log.md, and generated artifacts.

Operation: one bounded runtime action, such as inspecting a pack, preflighting readiness, validating or running one story, verifying a story, continuing retained work, or closing out an epic through review, fix, and reverify.

Envelope: the structured result returned by every CLI and SDK operation. Envelopes include status, outcome, errors or warnings, timestamps, operation data, and artifact references.

Artifact: a durable file written back into the spec pack. Artifacts make implementation, verification, continuation, and release evidence auditable after the agent run is over.

Provider: an external agent CLI used for implementation or verification work. Current adapters support Claude Code and Codex.

Install

npm install lbuild-impl

You can also use the CLI directly with npx:

npx lbuild-impl --help

lbuild-impl requires Node 24 or newer.

Try It Out

Start with read-only inspection:

npx lbuild-impl inspect --spec-pack-root ./docs/spec-build/epics/my-epic --json

Then run preflight checks:

npx lbuild-impl preflight --spec-pack-root ./docs/spec-build/epics/my-epic --json

Both commands return JSON envelopes. inspect is read-only. Commands that perform implementation or verification write artifacts back into the spec pack.

The normal story path is:

npx lbuild-impl story-orchestrate validate --spec-pack-root ./docs/spec-build/epics/my-epic --story-id 00-foundation --json
npx lbuild-impl story-orchestrate run --spec-pack-root ./docs/spec-build/epics/my-epic --story-id 00-foundation --json

The normal epic closeout path is:

npx lbuild-impl epic-review --spec-pack-root ./docs/spec-build/epics/my-epic --json
npx lbuild-impl epic-fix --spec-pack-root ./docs/spec-build/epics/my-epic --fix-batch ./docs/spec-build/epics/my-epic/artifacts/fix/001-epic-fix-batch.md --json
npx lbuild-impl epic-reverify --spec-pack-root ./docs/spec-build/epics/my-epic --review-report ./docs/spec-build/epics/my-epic/artifacts/epic/001-epic-review.json --json

In practice, epic closeout is a loop:

epic-review -> epic-fix -> epic-reverify -> repeat until converged

The final epic gate remains orchestrator-owned and is not implicitly run by the CLI.

Example envelope shape:

{
  "version": 1,
  "command": "inspect",
  "status": "ok",
  "outcome": "ready",
  "artifacts": []
}

CLI Operations

| Command | Purpose | | ------- | ------- | | inspect | Read-only spec-pack inspection and summary | | preflight | Readiness checks before running implementation work | | story-implement | Run implementation for one story | | story-orchestrate | Run, resume, or inspect one durable story-lead attempt | | story-continue | Continue a resumable story operation | | story-self-review | Run story self-review passes | | story-verify | Verify story completion against the spec | | quick-fix | Run a bounded fix pass from verification findings | | epic-review | Run the fresh wide-net epic review pass | | epic-fix | Run a bounded epic-level fix pass from a curated fix batch | | epic-reverify | Continue epic closeout review against prior canonical findings | | skill | Read CLI-delivered skill onboarding and reference docs in bounded markdown chunks |

Implementation commands support the same envelope-oriented contract through the CLI and SDK. The skill command is intentionally model-facing markdown instead of an operation envelope.

Provider-backed commands emit caller-facing heartbeat summaries on stderr while work is still running. Those heartbeats are for the live caller harness that is monitoring the command, and they do not change the exact final JSON envelope on stdout.

For story-orchestrate, explicit unknown run ids return invalid-story-run-id on resume and status instead of silently selecting another attempt. Resume results also surface durable persisted review-request or ruling artifact refs when those caller inputs are accepted.

For multi-reviewer epic review, epic-review returns the canonical reconciled review result, not just the raw reviewer lane outputs. The individual reviewer outputs remain in the envelope as evidence.

CLI-Delivered Skill

lbuild-impl can deliver its orchestration skill directly through the CLI, so a coding agent can onboard without a separately installed skill bundle:

lbuild-impl skill ls-impl
lbuild-impl skill ls-impl onboarding/01-orientation.md 1

The initial load prints the authored skill root page plus an auto-generated directory of every loadable skill document, including chunk counts and exact follow-up commands. Chunk reads return plain markdown with a line range and carry-forward guidance.

SDK Usage

import { inspect, loadSkill, preflight, readSkillChunk } from "lbuild-impl/sdk";

const inspection = await inspect({
  specPackRoot: "./docs/spec-build/epics/my-epic",
});

const readiness = await preflight({
  specPackRoot: "./docs/spec-build/epics/my-epic",
});

const skillRoot = loadSkill({ skillName: "ls-impl" });
const orientation = readSkillChunk({
  skillName: "ls-impl",
  path: "onboarding/01-orientation.md",
  chunkNumber: 1,
});

Contract and error exports are available from:

import type { OperationEnvelope } from "lbuild-impl/sdk/contracts";
import { InvalidInputError } from "lbuild-impl/sdk/errors";

Provider Setup

Provider-backed operations require the relevant external CLI to be installed and authenticated.

Current provider binaries:

• Claude Code: claude
• Codex: codex

Common credentials:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY

Depending on the provider and local setup, authentication may come from CLI login state instead of environment variables alone. Provider-free commands such as inspect can run without these credentials. Real implementation and verification operations depend on the provider selected by the spec pack's run config.

What To Expect

The runtime is designed for traceable execution, not chatty interactive coding.

• Commands return structured envelopes.
• Mutating operations write artifacts into the spec pack.
• Provider operations can take time and may return continuation handles.
• Story work normally starts with story-orchestrate validate, then story-orchestrate run.
• Epic closeout normally uses epic-review, epic-fix, and epic-reverify.
• Failures should be inspectable through status, outcome, error details, and artifacts.
• Historical epic docs are build history; current-state docs describe the implementation as it exists now.

Development

git clone https://github.com/liminal-ai/lbuild-impl.git
cd lbuild-impl
npm ci
npm run verify

Useful gates:

npm run verify                  # format check, lint, typecheck, and unit tests
npm run test:package            # package, release, dist, and install tests
npm run test:integration        # real-provider integration tests
npm run verify-all              # default, package, and integration gates
npm run pack-and-install-smoke  # local npm pack/install smoke

Project Structure

src/
  bin/                 # CLI entrypoint
  cli/                 # CLI command wrappers and output helpers
  sdk/                 # Public SDK operations, contracts, and errors
  core/                # Runtime orchestration and provider adapters
  infra/               # Filesystem and environment helpers
  prompts/             # Embedded operation prompts
  skills/              # Editable CLI-delivered skill markdown
  references/          # Embedded reference material
scripts/
  sync-impl-cli-assets.ts # Embeds prompts and skill markdown for package builds
tests/
  unit/                # Default fast test project
  package/             # Package, release, workflow, and install tests
  integration/         # Real-provider integration tests
  support/             # Shared test helpers and fixtures
gorilla/               # Release evidence fixture and operator prompt
docs/
  current-state*.md    # Current implementation baseline
  release-runbook.md   # Maintainer release procedure

Release

Release automation uses Blacksmith-hosted GitHub Actions runners for verification gates and a GitHub-hosted runner for the final npm publish so provenance can be attached. The publish workflow gates live publication on:

• default CI
• package/release tests
• real-provider integration tests
• committed gorilla evidence
• release marker/version sync

See docs/release-runbook.md for the maintainer procedure.

Read Next

• Current State
• Current State Tech Design
• Current State Code Map
• Release Runbook
• Changelog

Status

Indie open-source pre-release (0.4.0). The CLI and SDK are usable, but the API and workflow vocabulary may still evolve as the broader Liminal Build platform stabilizes.

License

MIT