Skip to content
stacks
Docs menu

Quickstart

Install the CLI, write a Go CLI project from a stack, and hand it to your agent until verify comes back green.

View as MarkdownOpen in ClaudeOpen in ChatGPT

This page installs the CLI and takes one Go CLI project from search to a green verify, with your coding agent doing the build.

Requirements

You need:

  • Node 22 or later, on macOS or Linux. npm and npx come with it.
  • git.
  • A coding agent on your PATH if you want stacks to hand the project over for you: Claude Code (claude) or Codex CLI (codex) are the best supported. Without one, stacks prints the prompt to give your agent yourself.
  • The tools the stack builds with. This page uses go-cli, which needs Go and make. You can follow along without them; stacks warns about missing tools instead of failing.

Install

The package on npm is @steamfield/stacks. The command it puts on your PATH is stacks.

npm install -g @steamfield/stacks@latest
stacks --version
Terminal

If you'd rather not install anything globally, put npx @steamfield/stacks@latest wherever this page says stacks. Every command works the same way, and the brief records the exact command your agent should use for verify.

The first time you run a command, stacks prints a one-time notice on stderr about anonymous usage telemetry. That run sends nothing. If you don't want it, turn it off now:

stacks telemetry disable
Terminal

The telemetry page lists what's collected and every off switch.

Find a stack

A stack is a recipe for one kind of project. Describe what you want in plain words:

stacks search "Go command line tool" --kind stack --limit 3
Terminal
stack go-cli (strong)
A Go command-line tool with subcommands, configurable settings, actionable errors and human or JSON output.
Why: cli (platforms); cli-tool (productKinds); Go (id, name, tags); Go command line (description, summary); Go command (body); command (requests, goodFor); command line (useCases)
...
stack typescript-cli (strong)
A compiled command-line tool with subcommands, JSON results, lazy configuration and structured logs.
...
Next: stacks show go-cli, then stacks new go-cli <dir>.
Output

Each hit says how well it fits (strong or partial) and why: which of your words matched which part of the entry. search asks the hosted API at stacks.steamfield.io and ranks locally at the same time, so it still works offline. stacks list stacks prints the whole catalog, and you can browse it at stacks.steamfield.io/stacks/.

Review the stack

stacks show prints the whole recipe without writing anything:

stacks show go-cli
Terminal
Go CLI (go-cli), stack, origin bundled, trusted
A starter for a terminal program written in the Go language, with settings and clear error messages.
...
Tools: go, make, git, golangci-lint
Decisions:
  - Binary name: the project slug (default; the Makefile's BIN).
  - Coverage floor: 50% (default).
  ...
Fragments: required none; default agent-ops, git-hooks, ci-github; optional goreleaser, rr, ce-plugin
Verify:
  install: make install (phase setup, layer install)
  build: make build (layer build)
  vet: make vet (layer typecheck)
  lint: make lint (layer lint)
  test: make test (layer test)
  ...
Output

Decisions lists what your agent will ask you, each with a default. Fragments lists the add-ons the stack pulls in, and Verify lists the checks that must pass before the project counts as done.

Preview the project

A dry run composes everything and writes nothing:

stacks new go-cli my-cli --sandbox --dry-run
Terminal
Planned my-cli from go-cli (sandbox).
Fragments: agent-ops, ci-github, git-hooks
Agents: claude
Git: would create a new repository
Would write 20 files:
  .claude/ (10 files)
  .editorconfig
  .gitignore
  .stacks/ (4 files)
  AGENTS.md
  CLAUDE.md
  Makefile
  README.md
Brief: .stacks/BRIEF.md (3272 words)
Dry run: nothing was written.
Output

--sandbox means local only. Your agent takes the default for every decision instead of asking you, deploy and release fragments stay out, and nothing is published. It's the fastest way to see a stack working. Leave it off for a real project, where the brief lists the decisions your agent should bring to you.

Create the project

Run the same command without --dry-run:

stacks new go-cli my-cli --sandbox
Terminal
Created my-cli from go-cli (sandbox).
Fragments: agent-ops, ci-github, git-hooks
Agents: claude
Git: new repository, nothing committed
Brief: .stacks/BRIEF.md (3272 words)
...
Output

stacks writes the starter files, runs git init, and starts your coding agent in my-cli/ with one instruction: read .stacks/BRIEF.md and carry it out. From here you're talking to the agent.

If you'd rather start the agent yourself, add --no-launch (in a fresh directory). stacks prints the prompt instead, and you open my-cli/ in your agent and paste it.

stacks new go-cli my-cli --sandbox --no-launch
Terminal

The agent works through the brief: it writes the code, installs current versions of the packages the stack names, and runs stacks verify after each round of fixes. Your part is answering the questions the brief tells it to ask. With --sandbox there are none.

The files in .stacks/

Most of what new wrote is ordinary project files: a Makefile, README.md, AGENTS.md, Claude Code settings and hooks under .claude/. The part stacks owns is .stacks/:

File What it is Committed
BRIEF.md The agent's task: what to build, which decisions to ask about, and the checks that must pass No
manifest.json Which stack and fragments the project came from, and its verify steps Yes
NOTES.md Where the agent records questions it asked you and problems it found in the brief No
state/ Verify's run history No

The brief runs to a few thousand words, written for the agent to read in full. Skim its "Decisions" and "Definition of done" sections to see what you're getting. The brief and the manifest covers both files.

Run verify yourself

verify runs the steps in the manifest and reports which pass. You can run it at any point:

cd my-cli
stacks verify --all
Terminal

Run it straight after new and it fails at the first setup step, because the agent hasn't written anything yet. That's expected. Once the agent is done, the same command ends with outcome green and exit 0.

--all also runs the steps a sandbox project skips by default. Use it for the final check. A run limited with --only or --skip-tag can exit 0 with outcome partial, and partial never counts as done.

Important

Your agent can't edit the verify steps to get a pass. verify compares the steps against a copy recorded outside the project and refuses to run when they differ. If you change a step on purpose, accept it from your own terminal with stacks verify --accept-changes; agents are refused. Verify explains how.

A green verify proves the declared checks pass. Read the code your agent wrote the way you'd review any change.

View the verify history

stacks runs
Terminal

runs summarizes the project's verify runs: how many there were, the last outcome, how long it took to reach the first green run, and how many times the agent had to ask you something.

Uninstall

Remove the CLI with npm:

npm uninstall -g @steamfield/stacks
Terminal

stacks also keeps a few directories in your home folder. Delete the ones you don't want:

Path What it holds
~/.config/stacks/ config.json and your own stacks and fragments
~/.local/share/stacks/ Data
~/.local/state/stacks/ Project state records and telemetry state
~/.cache/stacks/ Cached index, stats and search data
~/.claude/skills/stacks/ The agent skill, if you installed it

If you've set XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME or XDG_CACHE_HOME, the directories live under those instead. stacks doctor prints the paths it uses. Projects you created keep working without stacks; only stacks verify needs it.

Next steps