spec

command module

v0.36.0 Latest Latest Go to latest Published: Jul 13, 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 — developer workflow in the terminal

spec is a terminal control plane for turning an idea into reviewed, implemented work.

It keeps specifications, pipeline state, decisions, review threads, build plans, and coding-agent context together. Markdown in Git remains the source of truth; the interactive terminal UI is where people read and move the work.

brew install aaronl1011/tap/spec
spec

On first run, spec opens an onboarding wizard. It collects your identity, connects you to your team's specs repository, and then opens the dashboard — no config files to find or commands to memorise first.

Demonstration of a spec review

New here? Follow the TUI-first quickstart.

What spec gives you

A daily terminal workspace. Run spec to see what to do, what needs review, what is incoming, and what is blocked.
A readable review cockpit. Move through a spec section by section, traverse every discussion thread, anchor comments to exact blocks, filter review work, and track unread replies.
A configurable delivery pipeline. Teams define stages, ownership, advancement gates, warnings, and transition effects.
Git-backed specifications. Specs are structured Markdown, reviewable in normal Git tooling and usable without a hosted spec database.
Integrated build context. Build plans become a dependency graph that spec build can hand to Pi or Claude Code through MCP.
Progressive enhancement. Git is enough to start. Jira, Confluence, GitHub, Slack, Teams, deployment, and AI integrations are optional.
A scriptable CLI when you need it. TUI actions have command equivalents for automation, CI, hooks, and advanced workflows.

Install

Homebrew

brew install aaronl1011/tap/spec

Go

Requires Go 1.25.8 or newer.

go install github.com/aaronl1011/spec@latest

Prebuilt binaries

Download a release for Linux, macOS, or Windows from GitHub Releases.

Build from source

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

Verify the install:

spec version

Start here: run `spec`

spec

If this is your first run, the wizard guides you through two steps:

Identity — name, role, and an optional stable spec handle.
Team — join an existing specs repository using org/repo or a full GitHub, GitLab, or Bitbucket URL.

Set the provider token before starting, or paste it into the password field:

export SPEC_GITHUB_TOKEN="..."     # or SPEC_GITLAB_TOKEN / SPEC_BITBUCKET_TOKEN
spec

After joining, the wizard opens the dashboard directly.

Creating a brand-new team is an administrative path. Choose Create a new team in onboarding, then run spec config init in the repository that will hold spec.config.yaml. See Configuration.

Your first minute in the TUI

j / k or arrows   move
enter             open the selected item
1 … 6             Dashboard, Pipeline, Specs, Triage, Reviews, Settings
?                 help for the current screen
/                 search specs
esc               go back; twice at top level exits

A useful first pass:

Press 3 to browse all specs.
Select a spec and press enter for its overview.
Press o to open the reader.
Use ] / [ for sections and n / p for discussion threads.
Press esc to return, then 1 for your personal dashboard.

See the full TUI guide for lifecycle actions, triage, the review cockpit, and Settings.

The workflow

Capture work

Use i in the TUI for a lightweight triage item, or n for a full spec. A PM can promote a triage item later with p from its detail pane.

Shape and review the spec

Specs move through the team's configured pipeline. Ownership and gates make the next action visible without hiding the underlying document.

In the reader:

A selects a paragraph, list item, table row, or code block and asks a precisely anchored question;
n / p traverse matching threads across the whole document;
r, x, and u reply, resolve, or preserve something as unread;
f cycles open, all, mine, and unread views.

Plan and build

Engineers add build steps and dependencies to the technical plan. b in the TUI, or spec build, validates the plan and launches the configured coding agent with deterministic spec and repository context.

Advance with confidence

a advances the selected spec only after its current gates pass. Configured effects can publish documentation, update Jira, notify a channel, or trigger a webhook. Integration failures degrade without corrupting pipeline state.

TUI and CLI: clear responsibilities

Use the TUI for human workflow: onboarding, finding work, reading specs, triage, discussion, lifecycle actions, builds, and personal settings.

Use commands for explicit or automated tasks: scripts, CI, configuration administration, detailed build-plan editing, integration preflight, and MCP.

Once a spec is focused, commands can usually omit its ID:

spec focus SPEC-042
spec status
spec validate
spec build --check
spec do

The TUI and CLI share the same Git-backed specs, local focus, read-state, and build ledger.

Core concepts

Specs repository

The team repository contains the shared config at its root and the documents under specs/:

spec.config.yaml
specs/
├── SPEC-042.md
├── SPEC-042.threads.yaml
├── triage/TRIAGE-088.md
└── archive/SPEC-001.md

Joining creates a managed local clone at ~/.spec/repos/<owner>/<repo>/. spec reads and writes through that clone and publishes changes according to the team's sync.auto_push policy.

Pipeline

A pipeline is an ordered set of stages. Each stage may define:

one or more owning roles;
gates that must pass before advancement;
dashboard scope and claim behavior;
warnings, review requirements, and auto-advance rules;
effects on entry, exit, advance, or revert.

Choose a built-in preset or define stages directly. The interactive preset selector is available through spec config init.

Identity and ownership

Your local identity includes a name, role, stable spec handle, and optional provider-specific identities. It controls personal queues, section ownership, assignment matching, thread authorship, and integration calls.

Personal settings live in ~/.spec/config.yaml and are never committed. Shared team behavior lives in spec.config.yaml and is committed.

Focus

Focus is the CLI's working context. In the TUI press f on a spec; from the shell run spec focus SPEC-042. Commands such as status, advance, plan, steps, and build then infer that ID.

Documentation

Guide	Use it for
Quickstart	First run and first TUI workflow
TUI guide	Reader, review, triage, actions, Settings
Configuration	Team and pipeline config
Agent integration	MCP build-port contract
Team contract	Collaboration conventions
SPEC.md	Product specification and architecture
CHANGELOG.md	Release history

Use spec --help, spec <command> --help, and ? inside the TUI for the reference closest to your current task.

Development and contributing

Requires Go 1.25.8+ and Git.

make build
make test
make lint-strict
make docs

Read AGENTS.md before contributing. It defines architecture, Go, testing, lint, and commit conventions. Contributions use conventional commits and should reference the relevant product specification or discussion.

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.	Package confluence implements DocsAdapter using the Confluence REST API.
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/pi Package pi implements AgentAdapter for the pi.dev coding agent.	Package pi implements AgentAdapter for the pi.dev coding agent.
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.	Package ai provides the AI service layer for content drafting.
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.
identity Package identity resolves whether a stored handle or display name refers to a given person.	Package identity resolves whether a stored handle or display name refers to a given person.
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.
search Package search orchestrates the FTS5-backed spec search index and exposes a single Search entry point shared by the TUI overlay and the CLI.	Package search orchestrates the FTS5-backed spec search index and exposes a single Search entry point shared by the TUI overlay and the CLI.
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.
update Package update implements `spec update`: it brings the locally installed spec binary to the newest released version by delegating to whatever mechanism manages the install (Homebrew, go install, or a raw release binary it self-replaces).	Package update implements `spec update`: it brings the locally installed spec binary to the newest released version by delegating to whatever mechanism manages the install (Homebrew, go install, or a raw release binary it self-replaces).
urgency Package urgency computes how "stale" a task is from the time it has dwelt in its current pipeline stage, expressed as a 0..1 intensity for colour ramps.	Package urgency computes how "stale" a task is from the time it has dwelt in its current pipeline stage, expressed as a 0..1 intensity for colour ramps.
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