spec

command module

v0.12.1 Latest Latest Go to latest Published: Jun 1, 2026 License: MIT Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/aaronl1011/spec

Links

Open Source Insights

README ¶

spec — A Unified Developer Control Plane

spec was built for flow. Born from a desire for liberation from tangled webs of project-management software — free to solve problems in peace and serenity.

It unifies spec management, pipeline orchestration, build context, and team coordination into a single, fast, local-first CLI. Run spec with no arguments and you get an interactive terminal dashboard of everything awaiting your attention.

Demonstration of a spec review

New here? Jump straight to the QUICKSTART guide → to go from zero to productive in about 15 minutes.

Why spec?

One place for the work. Specs, pipeline state, decisions, reviews, and build context live together.
A pipeline that fits your team. Stages, gates, and automated effects are config-driven. Start from a preset, customise as you grow.
Markdown in git is the source of truth. No proprietary database, no lock-in. A spec is a structured SPEC-NNN.md you can read, diff, and review.
Local-first and resilient. Every integration is optional. Unconfigured tools use noop adapters. spec works fully offline.
Agent-ready. spec build assembles structured context for coding agents (Pi, Claude Code, Cursor, Copilot) over an MCP server or a context file.
AI is a bonus, never a requirement. Drafting features enhance the flow when configured and quietly step aside when they aren't.

Install

Homebrew

brew install aaronl1011/tap/spec

Go install

Requires Go 1.25+.

go install github.com/aaronl1011/spec@latest

Prebuilt binaries

Download from GitHub Releases for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64.

Build from source

git clone https://github.com/aaronl1011/spec.git
cd spec
make build      # → ./bin/spec

Verify:

spec version
spec --help

Shell completions & man pages

make install              # build + install to ~/.local/bin
make install-completions  # auto-detects bash / zsh / fish
make install-man          # install man pages (spec(1), spec-advance(1), …)

The 30-second tour

spec config init --user        # set up your identity (once)
spec join acme/specs           # join your team's specs repo
spec                           # open the interactive dashboard
spec new --title "Auth fix"    # scaffold a spec
spec focus SPEC-042            # set your working context
spec do                        # resume where you left off

Once you spec focus a spec, most commands infer the ID automatically — no need to repeat it. The full walkthrough lives in the QUICKSTART guide →.

Core concepts

The spec

A SPEC-NNN.md is a structured markdown document with YAML frontmatter and role-scoped sections.  markers define who can write to each section, which powers section-scoped sync (a PM edits the problem statement in Confluence, an engineer edits the technical plan in the terminal) and gate validation (you can't advance past design if the design inputs are empty).

The pipeline

Specs flow through configurable stages — each with an owner role, gates that must pass before advancing, and effects that fire on transition (notify a channel, sync to docs, log a decision). Start from a preset (minimal, startup, product, platform, kanban) and customise from there.

Focus mode

Most commands operate on a single spec. Set a focused spec once with spec focus and it persists across terminal sessions, so spec status, spec advance, spec build, and friends all just work. Pass an explicit ID to override for one command.

The TUI

Running spec in an interactive terminal launches a persistent dashboard with six tabs — Dashboard, Pipeline, Specs, Triage, Reviews, Settings — full keyboard navigation, drill-down spec reading, and inline actions (advance, block, focus, build, decide, …). In non-interactive contexts (pipes, CI) it falls back to a static render; force it with --static.

For the complete command reference, configuration schema, and keybindings, see the QUICKSTART guide →.

Development

Prerequisites

Go 1.25+
Git

Common tasks

make build        # → ./bin/spec
make install      # → $BINDIR/spec (default ~/.local/bin)
make test         # go test ./... -race -count=1
make test-cover   # coverage report → coverage.html
make lint         # go vet + golangci-lint
make fmt          # gofmt -s -w .
make docs         # regenerate man pages into docs/man/

Contributing

Contributions are welcome. To keep the codebase coherent:

Read AGENTS.md — it defines the Go standards, naming, error handling, and design principles (KISS, loose coupling, robustness) we hold to.
Adding a command: create cmd/<name>.go (flags only), call into internal/ for all logic, and register it with rootCmd.AddCommand() in init().
Adding an adapter: implement the category interface from internal/adapter/<category>.go in internal/adapter/<provider>/, then wire it into the registry by provider string — engine code never changes.
Commits: use Conventional Commits (feat:, fix:, refactor:, test:, docs:, chore:). One logical change per commit.
Before opening a PR: run make fmt lint test clean. PR descriptions should reference the spec (Implements US-12 / Addresses §7.9).

The full product specification and PR stack plan live in SPEC.md.

Project layout & further reading

Document	Purpose
QUICKSTART.md	Setup, configuration, and day-to-day usage
SPEC.md	Full product specification and PR stack plan
AGENTS.md	Coding standards for contributors and AI agents
CHANGELOG.md	Release history
`docs/man/`	Generated man pages (`make docs` to regenerate)

License

MIT

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

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

Path	Synopsis
cmd
internal
adapter Package adapter defines interfaces for all external integrations.	Package adapter defines interfaces for all external integrations.
adapter/anthropic Package anthropic implements AIAdapter using the Anthropic Messages API.	Package anthropic implements AIAdapter using the Anthropic Messages API.
adapter/claude Package claude implements AgentAdapter for Claude Code.	Package claude implements AgentAdapter for Claude Code.
adapter/confluence Package confluence implements DocsAdapter using the Confluence REST API v2.	Package confluence implements DocsAdapter using the Confluence REST API v2.
adapter/github Package github implements RepoAdapter and DeployAdapter using the GitHub API.	Package github implements RepoAdapter and DeployAdapter using the GitHub API.
adapter/jira Package jira implements PMAdapter using the Jira REST API v3.	Package jira implements PMAdapter using the Jira REST API v3.
adapter/noop Package noop provides no-op adapter implementations for unconfigured integrations.	Package noop provides no-op adapter implementations for unconfigured integrations.
adapter/ollama Package ollama implements AIAdapter using the Ollama local API.	Package ollama implements AIAdapter using the Ollama local API.
adapter/resolve Package resolve creates concrete adapter implementations from team config.	Package resolve creates concrete adapter implementations from team config.
adapter/slack Package slack implements CommsAdapter using the Slack API.	Package slack implements CommsAdapter using the Slack API.
adapter/teams Package teams implements CommsAdapter using Microsoft Teams webhooks.	Package teams implements CommsAdapter using Microsoft Teams webhooks.
ai Package ai provides the AI service layer for content drafting, summarisation, and semantic search.	Package ai provides the AI service layer for content drafting, summarisation, and semantic search.
awareness Package awareness provides passive awareness about pending items.	Package awareness provides passive awareness about pending items.
build Package build orchestrates the coding agent integration.	Package build orchestrates the coding agent integration.
config Package config handles loading and resolution of team and user configuration.	Package config handles loading and resolution of team and user configuration.
dashboard Package dashboard aggregates signals from all configured adapters into a single terminal view.	Package dashboard aggregates signals from all configured adapters into a single terminal view.
git Package git wraps all git CLI interactions.	Package git wraps all git CLI interactions.
markdown Package markdown provides parsing and mutation for SPEC.md files.	Package markdown provides parsing and mutation for SPEC.md files.
mcp Package mcp implements the MCP (Model Context Protocol) stdio transport.	Package mcp implements the MCP (Model Context Protocol) stdio transport.
metrics
onboard Package onboard handles team onboarding workflows.	Package onboard handles team onboarding workflows.
pipeline Package pipeline implements the spec pipeline stage machine.	Package pipeline implements the spec pipeline stage machine.
pipeline/effects Package effects executes pipeline transition effects.	Package effects executes pipeline transition effects.
pipeline/expr Package expr provides expression evaluation for pipeline gates.	Package expr provides expression evaluation for pipeline gates.
planning Package planning handles technical plan creation and review workflows.	Package planning handles technical plan creation and review workflows.
steps Package steps handles build step execution and transitions.	Package steps handles build step execution and transitions.
store Package store handles all SQLite persistence for spec.	Package store handles all SQLite persistence for spec.
sync Package sync coordinates section-scoped synchronization between local specs and docs providers.	Package sync coordinates section-scoped synchronization between local specs and docs providers.
syncaudit Package syncaudit bridges the git sync layer to the SQLite store.	Package syncaudit bridges the git sync layer to the SQLite store.
thread Package thread provides inline Q&A threads for spec review.	Package thread provides inline Q&A threads for spec review.
tui Package tui provides interactive terminal UI components for spec.	Package tui provides interactive terminal UI components for spec.
tui/components Package components provides reusable TUI building blocks.	Package components provides reusable TUI building blocks.
tui/glyph Package glyph is the single source of truth for every glyph the TUI renders.	Package glyph is the single source of truth for every glyph the TUI renders.
tui/watch Package watch observes a fixed set of files for changes and emits debounced, coalesced notifications.	Package watch observes a fixed set of files for changes and emits debounced, coalesced notifications.
workflow Package workflow holds the orchestration logic for spec pipeline transitions — advance, revert, eject, resume.	Package workflow holds the orchestration logic for spec pipeline transitions — advance, revert, eject, resume.
tools
gen-man command