pipeline-sdk

YAML-driven pipeline orchestration for AI agents.

Why?

AI coding agents (Claude Code, Cursor, Windsurf, and others) execute multi-step workflows -- write code, run tests, deploy -- but lack a structured way to enforce stage gates, track evidence, or coordinate handoffs. pipeline-sdk gives your agent a state machine: define stages in YAML, gate transitions on passing tests, and keep a cryptographic audit trail of what happened.

What is this?

Define multi-stage pipelines in YAML with gates, evidence chains, and cleanup handlers. The SDK provides a state machine engine, HTTP daemon, CLI, and MCP server to orchestrate AI agent workflows. Pipelines are declarative, auditable, and resumable.

Quick Start

# Install
bun add pipeline-sdk

# Initialize a pipeline from a template
bunx pipeline init

# Start the daemon
bunx pipeline start

# In another terminal -- check status
bunx pipeline status

# Advance to the next stage
bunx pipeline advance STAGE_COMPLETE

Architecture

pipeline.yaml --> StateMachine --> PipelineDaemon (HTTP localhost:<port>)
                                        |
                                  MCP Server <--> AI Agent
                                        |
                                  Evidence Chain

The YAML file defines stages and transitions. The state machine enforces the rules. The daemon exposes an HTTP API. The MCP server lets AI agents participate natively. Every transition is recorded in a tamper-evident evidence chain.

Key Concepts

Stages -- Named phases of your pipeline (e.g., dev, review, deploy). Each stage can define entry/exit actions, gates, and cleanup handlers.

Events and Transitions -- Events like DEV_DONE trigger transitions between stages. Transitions can be conditional, requiring gates to pass before proceeding.

Gates -- Preconditions that must be satisfied before a transition completes:

• Builtin -- automated checks (lint, test, typecheck)
• Custom -- shell commands or scripts
• Async -- external signals (human approval, CI completion)

Evidence Chain -- A cryptographically linked log of every transition, gate result, and signal. Provides a verifiable audit trail for the entire pipeline run.

Adapters -- Pluggable system for integrating with external tools (CI systems, deployment platforms, notification services).

CLI Reference

| Command | Description | |---------|-------------| | pipeline init | Initialize a new pipeline from a template | | pipeline start | Start the pipeline daemon | | pipeline status | Show current stage and pipeline state | | pipeline advance <event> | Emit an event to trigger a transition | | pipeline signal <gate> | Signal an async gate as satisfied | | pipeline verify | Verify evidence chain integrity | | pipeline resume | Resume pipeline from saved state | | pipeline cleanup | Run cleanup handlers and stop the daemon | | pipeline validate | Validate pipeline.yaml against the schema | | pipeline visualize | Generate a Mermaid state diagram | | pipeline template [name] | List or apply a built-in template |

Built-in Templates

| Template | Description | |----------|-------------| | sdlc-full | Complete software development lifecycle with review and deploy gates | | static-site | Web portfolio pipeline with accessibility gates | | dual-model | Dual-model development pipeline with consensus-based quality gates | | infra-gitops | Infrastructure deployment with approval gates and rollback |

MCP Integration

The SDK exposes an MCP server so AI agents can participate in pipelines natively:

• 4 tools -- check, advance, signal, status
• 3 resources -- current state, stage instructions, gate status
• 1 prompt -- stage context for the active phase

The MCP server is created programmatically via createMcpServer() and communicates over stdio. See MCP Integration for setup details. AI agents like Claude Code can then query pipeline state, advance stages, and signal gates through the standard MCP protocol.

API Usage

import { loadPipeline, StateMachine } from "pipeline-sdk";

const pipeline = await loadPipeline("pipeline.yaml");
const sm = new StateMachine(pipeline);

console.log(sm.currentStage); // "dev"

const result = sm.transition("DEV_DONE");
console.log(result.newStage); // "review"

Evidence Store

import { EvidenceStore } from "pipeline-sdk";

const store = new EvidenceStore(".pipeline/evidence");
const result = await store.verify();
console.log(result.valid, result.recordCount);

Documentation

• Getting Started
• CLI Reference
• Pipeline YAML Reference
• Architecture
• MCP Integration

Development

bun install
bun test              # Run test suite
bun run lint          # Biome
bun run typecheck     # TypeScript
bun run build         # Compile to binary

Contributing

See CONTRIBUTING.md for development setup, commit conventions, and PR guidelines.

License

MIT