LineSpec captures the why behind your code with Provenance Records, surfaces insights with AI-powered semantic search, and tests the how with a DSL that intercepts protocols at the wire level.
brew tap livecodelife/linespec && brew install linespec
go install github.com/livecodelife/linespec/cmd/linespec@v1.3.0
Structured YAML artifacts that capture architectural intent, constraints, and scope. Query your decision history. Enforce boundaries at commit time.
DSL-based integration testing that intercepts database and HTTP traffic at the protocol level. Language-agnostic. Deterministic.
Structured YAML artifacts that capture the why, not just the what.
id: prov-2026-a1b2c3d4
title: "Use PostgreSQL for primary data store"
status: open
created_at: "2026-03-15"
author: "dev@example.com"
intent: >
After evaluating options, we choose PostgreSQL for our
primary data store due to better JSON support and
concurrent write handling.
constraints:
- All new tables must use PostgreSQL
- Use connection pooling (min 10, max 100)
affected_scope:
- pkg/db/**
- migrations/**
tags:
- architecture
- databaseCapture not just what changed, but why. Every record documents the reasoning behind architectural decisions.
Define affected and forbidden scopes. Pre-commit hooks validate that changes stay within boundaries.
Visualize relationships between decisions. Track what supersedes what. Query your architectural history.
Find related decisions with natural language queries. Uses embeddings to surface semantically similar records.
linespec provenance create
Create a new record with auto-generated ID
linespec provenance lint
Validate all records for schema compliance
linespec provenance graph
Render the decision graph
linespec provenance search
Semantic search across records
linespec provenance complete
Mark a record as implemented
linespec provenance install-hooks
Set up git integration
Semantic search powered by embeddings. Query your architectural decisions in natural language.
Search with plain English. No need to remember exact keywords or tags. The AI understands intent.
Records are indexed automatically when marked complete. GitHub Actions support for team-wide search indexes.
Choose your embedding provider. Works with Voyage AI (voyage-4) or OpenAI (text-embedding-3).
Use linespec provenance audit to check if your planned changes conflict with past decisions.
provenance:
embedding:
provider: voyage
index_model: voyage-4-large
query_model: voyage-4-lite
api_key: ${VOYAGE_API_KEY}
similarity_threshold: 0.50
index_on_complete: trueDSL-based integration testing that intercepts traffic deterministically.
-tags beta to enable
LineSpec Testing is a DSL-based integration testing framework for containerized services. It intercepts database and HTTP traffic at the protocol level, making tests language-agnostic and framework-independent.
TEST create-user
RECEIVE HTTP:POST http://localhost:3000/users
WITH {{payloads/user_create_req.yaml}}
HEADERS
Authorization: Bearer token123
EXPECT WRITE:MYSQL users
WITH {{payloads/user_db_record.yaml}}
VERIFY query MATCHES /\bpassword_digest\b/
VERIFY query NOT_CONTAINS '`password`'
RESPOND HTTP:201
WITH {{payloads/user_create_resp.yaml}}
NOISE
body.id
body.created_atIntercepts MySQL, PostgreSQL, HTTP, and Kafka traffic at the wire level. No code changes required.
linespec proxy mysql :3307 localhost:3306
No inference or heuristics. Every test runs the same way every time. Predictable results.
Tests are written in the LineSpec DSL, not your implementation language. Works with any backend.
Built-in operators for asserting query structure. Verify security constraints directly.
VERIFY query MATCHES /\bcolumn_name\b/
Install LineSpec and create your first provenance record.
brew tap livecodelife/linespec
brew install linespecgo install github.com/livecodelife/linespec/cmd/linespec@v1.3.0go build -tags beta -o linespec ./cmd/linespecUse Homebrew or Go install to get the CLI
linespec provenance create --title "Your decision"
linespec provenance lint
linespec provenance install-hooks
Join teams using LineSpec to document architectural decisions and enforce scope boundaries.