specrig-go

module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT

README

specrig-go

The Go side of specrig: what a Go stack needs to agree with the protocol, and the adapter that brings it to a service built on waffle.

what
agents specrig.md, agents/1: the parts every stack shares with a stack's slots filled, the rows of its mode and area tables, and the verdict on whether AGENTS.md brings it in
rules rules/1: the modes and classes of the protocol's table, a service's areas with its marker's merged in and checked, and the document a stack's tool prints for the plugin
cli the commands every stack's tool answers — init, which lays a service out for specrig; rules; and agents, which writes specrig.md and fails while AGENTS.md does not bring it in — with what differs by framework in a Preset, an adapter's own commands among it
surface the surface/1 record, and the check of a set of them against each other
trace what crossed a service's edge during a run, the records flows/1 is written from
flows flows/1: a suite's record written from its trace, and index/1: a project's flows assembled from its services' records
cmd/specrig-flows the command that assembles them, for a project on any stack
resource the seam between a component test and the external systems it runs against for real
standin the stand-in for a service's HTTP neighbour: it answers what the steps declared, holds or times out a call on request, checks the traffic against the neighbour's OpenAPI document and keeps what was sent
waffle the adapter for a service built on waffle, the Go framework, in a module of its own: the layout, the default areas and the text of specrig.md, the component harness generated from the container, what a test may replace, the surface read off the code, and the trace over gorib's transports

A framework's adapter hands cli.Main its Preset: the layout, the default areas, the slots and sections of specrig.md that are its own, and its own commands. The core fills the rest and reads the service's specrig.yaml.

A waffle service takes the adapter as a tool, once:

go get -tool github.com/specrig/specrig-go/waffle/cmd/specrig
go tool specrig init
go mod tidy

init writes specrig.yaml naming the tool as its guard, brings specrig.md into AGENTS.md, and scaffolds the harness. After that the service runs go tool specrig agents, rules, harness, replacements and surface. What each writes and why is under waffle/docs: the harness, the first component test, the commands, flows and the approach.

The Claude Code plugin that enforces the modes for every stack is specrig.

A project's flows

specrig-flows <root> <index.yaml>

reads the records of every service below root — Go, PHP, .NET or a web app — as one system, and writes the index of its flows and a page per flow beside it, as the protocol's system.md says. Each release carries it for macOS, Linux and Windows on amd64 and arm64, with checksums.txt:

curl -fsSLO https://github.com/specrig/specrig-go/releases/latest/download/specrig-flows-linux-amd64
curl -fsSLO https://github.com/specrig/specrig-go/releases/latest/download/checksums.txt
shasum -a 256 --check --ignore-missing checksums.txt

A Go module takes it as a tool instead:

go get -tool github.com/specrig/specrig-go/cmd/specrig-flows

and runs go tool specrig-flows.

Development

make test

runs the packages, and the adapter's, against the copy of the protocol in internal/protocol — its data embedded, its agents, markers, records and flows fixtures read by the tests.

make release

builds specrig-flows for every platform into dist/, with checksums.txt; a tag v<version> pushed does it in CI and attaches them to the release.

make protocol

refreshes that copy from a checkout of the protocol at PROTOCOL, ../protocol by default.

Directories

Path Synopsis
Package agents writes specrig.md from the parts every stack shares, agents/1, with a stack's slots filled, and judges whether AGENTS.md brings it in.
Package agents writes specrig.md from the parts every stack shares, agents/1, with a stack's slots filled, and judges whether AGENTS.md brings it in.
Package cli is the core of a Go stack's tool: the commands every stack answers, with what differs by framework in a Preset.
Package cli is the core of a Go stack's tool: the commands every stack answers, with what differs by framework in a Preset.
cmd
specrig-flows command
Command specrig-flows assembles a project's flows from its services' records, whatever stack each service is on.
Command specrig-flows assembles a project's flows from its services' records, whatever stack each service is on.
internal
Package resource is the seam between a component test and the external systems it runs against for real.
Package resource is the seam between a component test and the external systems it runs against for real.
Package rules is guard/1's rules/1: the modes and classes of the protocol's table, a service's areas, and the document a stack's tool prints for the plugin.
Package rules is guard/1's rules/1: the modes and classes of the protocol's table, a service's areas, and the document a stack's tool prints for the plugin.
Package standin is the stand-in for a service's HTTP neighbour: it answers what the steps declared, checks the traffic against the neighbour's OpenAPI document and keeps what was sent.
Package standin is the stand-in for a service's HTTP neighbour: it answers what the steps declared, checks the traffic against the neighbour's OpenAPI document and keeps what was sent.
Package trace keeps what crossed a service's edge during a run, as the records flows/1 is written from.
Package trace keeps what crossed a service's edge during a run, as the records flows/1 is written from.
waffle module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL