Overamp
A terminal music player: folder tree on the left, tracks in the middle, Now Playing on the right. Cross-platform Go, MP3 decoding, ID3 tags, incremental search, and a help overlay — three short specs, one agent, one binary.
dist/overamp — 5.4 MB Build it
One config, three specs, one command. Overplane raises each spec into a formal IR, checks it with Z3, and hands the whole contract to Claude Code inside a project sandbox. Unchanged specs hit the build cache on re-runs.
mkdir overamp && cd overamp
overplane init
overplane sandbox build
overplane spec new # 001-shape.md
overplane spec new # 002-playback-controls.md
overplane spec new # 003-library-niceties.md
overplane build all
The output directory is a complete Go module;
go build -o dist/overamp . produces the
dist/overamp binary shown in the screencast above.
The specs
This is everything the agent was given. Spec one shapes the three-pane player, spec two adds real transport controls, and spec three makes a big library browsable — tags, search, and in-app help.
001-shape.md
---
id: '#0001'
title: Shape
status: active
tags: [core]
---
# Shape
## Goal
Create a Go module in the working directory that builds a single binary called
`overamp`: a multi-pane console TUI for browsing a folder tree of MP3 files
and playing them on the system's default audio output. It must be
cross-platform (Linux, macOS, Windows). Well-maintained third-party Go
modules (TUI framework, MP3 decoding, audio output) are encouraged.
## Requirements
* CLI: `overamp [DIR]` where `DIR` defaults to `~/Music`. `overamp --help`
prints polished, colorized usage. A missing or empty directory produces a
friendly error, not a panic.
* Layout, three panes with visible borders and a title bar:
- Left: directory tree of `DIR`, folders only, expandable.
- Middle: MP3 files of the selected folder.
- Right: "Now Playing" — file name, folder, elapsed / total time, and a
progress bar that advances live during playback.
* Interaction: arrow keys (and vim keys) move within a pane, Tab switches
panes, Enter on a folder expands/selects it, Enter on a file plays it
(replacing any current playback), `q` quits cleanly and stops audio.
* Playback: decode MP3 and play on the system default output device. If audio
output is unavailable (e.g. headless), show a clear message in the Now
Playing pane instead of crashing.
* A persistent one-line footer lists the key bindings.
## Acceptance
- `go build -o overamp .` succeeds on Linux, macOS, and Windows targets
(`GOOS=darwin`/`windows` compile checks are enough for the non-host OSes).
- Launching against a folder with nested MP3s shows all three panes and the
footer; navigating and pressing Enter on a file starts playback and the
Now Playing pane updates.002-playback-controls.md
---
id: '#0002'
title: Playback Controls
status: active
tags: [polish]
---
# Playback Controls
## Goal
Turn `overamp` from a file player into a small music player: transport
controls and continuous play.
## Requirements
* Space pauses/resumes. Left/Right arrows in the Now Playing pane (or
`,` / `.` anywhere) seek back/forward 10 seconds. `-` / `+` adjust volume
in 10% steps; show the current volume in the Now Playing pane.
* When a track ends, automatically play the next MP3 in the current folder;
`n` / `p` skip to next/previous track manually.
* Reflect state everywhere: a play/pause glyph in the Now Playing pane and
the footer keys updated to include the new bindings.
* This spec refines spec #0001's playback behavior. When modeling it
formally, introduce new, distinctly named state (e.g. transport controls,
volume) rather than redeclaring spec #0001's playback state machine.
## Acceptance
- Pausing freezes the elapsed time; resuming continues from the same spot.
- Seeking past the end of a track advances to the next one.
- Volume changes are audible and the shown percentage tracks them.003-library-niceties.md
---
id: '#0003'
title: Library Niceties
status: active
tags: [feature]
---
# Library Niceties
## Goal
Make browsing a large library feel effortless: show real track metadata,
find files fast, and teach the keys in-app.
## Requirements
* ID3 tags: when a file has ID3 metadata, show artist — title in the file
list and artist / album / title in the Now Playing pane, falling back to
the file name when tags are missing or unreadable.
* Search: `/` opens an incremental filter over the current folder's files
(case-insensitive substring); Esc clears it. The match count is visible
while filtering.
* Help: `?` toggles a centered overlay listing every key binding, grouped
(Navigate / Playback / Library), dismissed by any key. The one-line footer
mentions `? help`.
* This spec adds library features on top of specs #0001-#0002. When modeling
it formally, introduce new, distinctly named state (e.g. filter, overlay)
rather than redeclaring earlier specs' state machines.
## Acceptance
- A tagged MP3 shows its artist and title instead of the raw file name.
- Filtering narrows the list as you type and Esc restores the full list.
- The help overlay opens, lists all bindings from specs 1-3, and closes.The result
Click the screencast above to watch a run against ~/Music:
browsing the folder tree, picking a track, and the Now Playing pane ticking
along with its progress bar. The footer teaches the keys;
? opens the full cheat sheet.