AGENT-LANG/spec-flow

Specification-driven development pipeline: natural language prompt → structured YAML spec → compiled test suite → generated implementation.

An LLM drafts a formal spec from your description, validates it, presents it for human approval, compiles it into a Vitest test file, then generates implementation code and auto-revises until all tests pass.

Pipeline

Prompt ──▸ Draft spec ──▸ Validate ──▸ Human review ──▸ Compile tests ──▸ Generate code
               ▲              │           │  ▲   ▲             │                 │
               └── auto-fix ──┘           │  │   │             │                 │
                                          │  │   └── reject ───┘                 │
YAML file ──▸ Load spec ─── validate ─────┘  │                            run tests
                                             │                            ▲     │
                                          Approve                         │     ▼
                                             │                            └ auto-revise
                                             └──────────────▸ Lock

The spec is the single source of truth. Tests are derived from it, code is written to satisfy the tests, and the human stays in the loop as gatekeeper.

Installation

npm install @agent-lang/spec-flow

As an MCP server

The quickest way to use spec-flow is as an MCP server with Claude Code or Claude Desktop:

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Run directly
npx @agent-lang/spec-flow

Or configure it in Claude Code settings:

{
  "mcpServers": {
    "spec-flow": {
      "command": "npx",
      "args": ["-y", "@agent-lang/spec-flow"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

As a library

import {
  Orchestrator,
  AnthropicProvider,
  validate,
  compile,
  emit,
} from "@agent-lang/spec-flow";

const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-sonnet-4-6",
});

const orchestrator = new Orchestrator(provider);

The server runs over stdio and exposes tools that any MCP-compatible client (Claude Desktop, Claude Code, etc.) can call.

MCP tools

| Tool | Description | |---|---| | generate_spec | Draft + validate + auto-revise a spec from a prompt | | load_spec | Load a spec from a YAML file, validate, and enter review | | save_spec | Write the current spec to disk as YAML | | approve_spec | Approve and lock the spec for compilation | | reject_spec | Revise the spec based on human feedback | | reopen_spec | Return an approved/locked spec to review | | compile_tests | Emit a Vitest test file from the locked spec | | generate_code | Generate implementation, run tests, auto-revise until passing | | run_tests | Run tests against generated or provided code | | get_status | Current pipeline state, revision count, errors | | diff_specs | Compare two specs with breaking-change flags | | update_spec | LLM-assisted targeted spec modification | | patch_spec | Programmatic spec operations (add/remove/update) | | check_impact | Analyze impact of spec changes on tests and code | | list_specs | List all specs with summary info | | spec_history | List version history of a named spec |

Multi-runtime support

Specs can target different runtimes via a pluggable architecture. Each runtime is a self-contained plugin implementing the RuntimePlugin interface:

• module (default) — TypeScript/JavaScript function. Tests import it directly.
• cli — Executable script (bash, node, python, etc.). Tests spawn it as a subprocess, capturing stdout/stderr/exit code.
• hugo — Hugo template (shortcode, partial, or layout). Tests scaffold a Hugo project, run hugo build, and assert on rendered HTML.

# CLI runtime
runtime:
  type: cli
  shell: node
  entrypoint: ./my-app

# Hugo runtime
runtime:
  type: hugo
  template_kind: shortcode   # shortcode, partial, or layout
  entrypoint: my-widget       # optional template name

Adding custom runtimes

New runtimes can be added by implementing RuntimePlugin and registering it — no changes to core files required:

import { defaultRegistry } from "@agent-lang/spec-flow";
import { myPlugin } from "./my-runtime/plugin.js";

defaultRegistry.register(myPlugin);

Configuration

| Variable | Description | Default | |---|---|---| | ANTHROPIC_API_KEY | Anthropic API key (required) | — | | AGENT_LANG_MODEL | Model to use for LLM calls | claude-sonnet-4-6 |

Development

npm run build      # Build for publishing (tsconfig.build.json)
npm run build:dev  # TypeScript compilation (includes tests)
npm test           # Run all tests
npm run test:watch # Watch mode

Project structure

src/
  schema/        # JSON Schema definitions for the spec format
  validator/     # Structural + semantic validation (8 rules)
  dialogue/      # State machine, orchestrator, system prompts
  compiler/      # Spec → Vitest test file
  runtime/       # Runtime plugin system (module/, cli/, hugo/)
  runner/        # Spawns Vitest to run generated tests
  gating/        # Tool registry + guard (blocks code-gen until approved)
  interfaces/    # LlmProvider and ToolBridge abstractions
  providers/     # AnthropicProvider (concrete LLM adapter)
  versioning/    # Spec evolution: metadata, diffing, impact analysis, registry
  adapters/      # MCP server (16 tools over stdio)
  index.ts       # Public API barrel export
  main.ts        # MCP server entry point
bin/
  spec-flow.mjs  # CLI entry point (npx @agent-lang/spec-flow)