Yet Another Spec Syntax — a YAML-based specification language for AI-agent-driven development. Specs capture desired behavior and are consumed to drive TDD and implementation generation.
🚧 Early work in progress.
- yass.yass.yaml— the yass language defined in yass itself.
- yass.v1.schema.json— JSON Schema for editor validation of- .yass.yamlfiles.
- cli/—- yass, a command-line program that serves an existing spec set to a coding agent, read-only toward every spec set. Install it per the section below, or build and run it per- cli/HOWTORUN.txt.
Releases publish prebuilt binaries for macOS (arm64, amd64), Linux (arm64, amd64), and Windows (amd64), with sha256 checksums, on the releases page. No Go toolchain is needed for any path below.
curl -fsSL https://raw.githubusercontent.com/shakefu/yass/main/install.sh | shThe installer detects the host OS and architecture, downloads the matching
archive for the latest stable release, verifies it against the release's
published checksum, and installs it into /usr/local/bin when that is
writable, else ~/.local/bin — telling you about any PATH setup it needs. Pin
a version or choose the directory:
curl -fsSL https://raw.githubusercontent.com/shakefu/yass/main/install.sh |
sh -s -- --version v0.2.0 --bin-dir "$HOME/bin"On Windows, download the windows_amd64 zip from the releases page instead.
brew tap shakefu/yass https://github.com/shakefu/yass
brew install yassThe formula (Formula/yass.rb) is regenerated with each
release, so brew update && brew upgrade yass moves to the newest one.
An installer-managed (or manually placed) binary updates itself:
yass updateIt checks the newest stable release, verifies the download against the
published checksum, and replaces the binary in place — preserving the working
installation if anything fails. A Homebrew-managed binary is left alone and
reported as such; upgrade it with brew upgrade yass.
Verify any installation with yass --version.
Build with Go per cli/HOWTORUN.txt.
yass is for working with a coding agent. You say what you want, the agent
writes it down as a spec the two of you agree on, and then an agent builds
exactly that. The yass command is how the agent finds its way around, and it
works with any agent that can run a shell command.
-
Install yass(above) and tell your agent to use it. One line in your project's agent instructions (AGENTS.md,CLAUDE.md, or the like) is enough:Run yasswith no arguments before writing, changing, or implementing a spec.
-
Ask for what you want. The output of that one command tells the agent which of three paths to take: - Starting something new — a project or feature with no spec yet. The agent runs the brainstorming flow: it asks what the thing is for, works through each behavior with you (proposing answers for you to correct rather than making you compose them), and drafts the spec. Nothing gets built until you have read the spec and said yes.
- Implementing a spec that exists — the agent reads the spec set through
yass, one document at a time rather than whole files, and builds what it says.
- Changing a spec — the agent reads the documents carried inside the
binary (yass docs), edits the spec files, and checks them withyass validateandyass lint.
-
Review the spec first. It is the contract the code is built against, so when something comes out wrong, the fix is usually a line in the spec — and the code follows.
Run yass with no arguments. It writes what the program is, what project the
current directory sits in, the notation a spec file uses, the commands that
read a spec set, and the flow that elicits a new one — enough to start without
opening a single file by hand.
The documents that define the language and how to write specs in it are
carried inside the binary and served by yass docs, so they travel with it
wherever it is installed. Read one when you are eliciting, writing, or changing
a spec; implementing against specs that already exist needs none of them.