stacks documentation
What stacks does, the steps from a stack to a green verify, what the CLI runs on your machine, and what you need installed.
# stacks documentation
> What stacks does, the steps from a stack to a green verify, what the CLI runs on your machine, and what you need installed.
stacks is a command-line tool that starts projects for coding agents. You pick a stack, stacks writes a few starter files and a build brief, your agent builds the project from the brief, and `stacks verify` runs the checks that define done.
## What stacks is for
A stack holds the setup knowledge that stays true for years: how to lay the project out, what to test, what "working" means. A person writes it down once. The knowledge that changes every few months, such as package versions, generator flags and config file formats, is left to your agent, which reads today's docs every time it builds.
So a stack never pins a version. It names packages by role ("cobra for commands, testify for tests"), the agent installs whatever is current, and the result has to pass a list of checks the agent can't change without your approval.
stacks is for people who already work with a coding agent such as Claude Code or Codex and want new projects to start from a tested layout with a definition of done.
## How a project gets built
1. **Find a stack.** `stacks search "Go command line tool"` ranks the catalog against your words. Browse it on the web at [stacks.steamfield.io](https://stacks.steamfield.io/stacks/).
2. **Review it.** `stacks show go-cli` prints everything the stack will tell your agent: the layout, the decisions it asks about, the checks, the files it ships.
3. **Write the project.** `stacks new go-cli my-cli` composes the stack with its fragments, writes the starter files and `.stacks/BRIEF.md`, runs `git init`, and hands the project to your agent.
4. **Your agent builds it.** The brief is the agent's whole task. It asks you only the decisions the brief tells it to ask.
5. **Verify until green.** The agent runs `stacks verify`, fixes what fails and runs it again. A project is done when `stacks verify --all` comes back `green`.
A fragment is one capability several stacks share, such as GitHub Actions CI or git hooks. Stacks pull in default fragments, and `--with` and `--without` change the set. [How stacks works](https://stacks.steamfield.io/docs/concepts.md) explains the model.
## What the CLI runs on your machine
stacks composes text and copies files. It doesn't generate application code, call a model, or run commands it reads from a stack or fragment: `verify` runs only the steps in your project's own `.stacks/manifest.json`, and it prints each one before running it.
The only other programs it starts are `git init` for a new project, the coding agent you hand the project to, and npm when you run `stacks update`.
`verify` proves the declared checks pass. It doesn't judge whether the code is good, so read what your agent wrote the way you'd read any pull request.
## Requirements
You need Node 22 or later on macOS or Linux, and git. Whatever the stack builds with (Go for `go-cli`, uv for `python-api`) has to be installed too; stacks lists anything missing instead of failing.
The [Quickstart](https://stacks.steamfield.io/docs/quickstart.md) installs the CLI and takes one project from search to a green verify.
## Start here
- [Quickstart](https://stacks.steamfield.io/docs/quickstart.md): Install the CLI, write a Go CLI project from a stack, and hand it to your agent until verify comes back green.
- [With your agent](https://stacks.steamfield.io/docs/agents.md): Install the stacks skill so your coding agent picks a stack, writes the project and loops on verify, and choose which agents a project is set up for.
- [How stacks works](https://stacks.steamfield.io/docs/concepts.md): How stacks, fragments, apps, presets and agent adapters fit together when stacks composes a project, with examples from the default registry.
- [Existing repository](https://stacks.steamfield.io/docs/guides/existing-repo.md): Apply fragments such as CI, git hooks or agent guardrails to a repository you already have, without stacks overwriting any of your files.
- [Write a stack](https://stacks.steamfield.io/docs/guides/authoring.md): Turn a project you trust into a stack or fragment in your user registry, validate it, preview its brief and test it with an agent build.
- [CLI commands](https://stacks.steamfield.io/docs/reference/commands.md): Every stacks command and subcommand, with its flags, defaults, JSON result schema, exit codes and examples.
View as MarkdownOpen in ClaudeOpen in ChatGPTstacks is a command-line tool that starts projects for coding agents. You pick a stack, stacks writes a few starter files and a build brief, your agent builds the project from the brief, and stacks verify runs the checks that define done.
What stacks is for
A stack holds the setup knowledge that stays true for years: how to lay the project out, what to test, what "working" means. A person writes it down once. The knowledge that changes every few months, such as package versions, generator flags and config file formats, is left to your agent, which reads today's docs every time it builds.
So a stack never pins a version. It names packages by role ("cobra for commands, testify for tests"), the agent installs whatever is current, and the result has to pass a list of checks the agent can't change without your approval.
stacks is for people who already work with a coding agent such as Claude Code or Codex and want new projects to start from a tested layout with a definition of done.
How a project gets built
- Find a stack.
stacks search "Go command line tool"ranks the catalog against your words. Browse it on the web at stacks.steamfield.io. - Review it.
stacks show go-cliprints everything the stack will tell your agent: the layout, the decisions it asks about, the checks, the files it ships. - Write the project.
stacks new go-cli my-clicomposes the stack with its fragments, writes the starter files and.stacks/BRIEF.md, runsgit init, and hands the project to your agent. - Your agent builds it. The brief is the agent's whole task. It asks you only the decisions the brief tells it to ask.
- Verify until green. The agent runs
stacks verify, fixes what fails and runs it again. A project is done whenstacks verify --allcomes backgreen.
A fragment is one capability several stacks share, such as GitHub Actions CI or git hooks. Stacks pull in default fragments, and --with and --without change the set. How stacks works explains the model.
What the CLI runs on your machine
stacks composes text and copies files. It doesn't generate application code, call a model, or run commands it reads from a stack or fragment: verify runs only the steps in your project's own .stacks/manifest.json, and it prints each one before running it.
The only other programs it starts are git init for a new project, the coding agent you hand the project to, and npm when you run stacks update.
verify proves the declared checks pass. It doesn't judge whether the code is good, so read what your agent wrote the way you'd read any pull request.
Requirements
You need Node 22 or later on macOS or Linux, and git. Whatever the stack builds with (Go for go-cli, uv for python-api) has to be installed too; stacks lists anything missing instead of failing.
The Quickstart installs the CLI and takes one project from search to a green verify.
Start here
- QuickstartInstall the CLI, write a Go CLI project from a stack, and hand it to your agent until verify comes back green.
- With your agentInstall the stacks skill so your coding agent picks a stack, writes the project and loops on verify, and choose which agents a project is set up for.
- How stacks worksHow stacks, fragments, apps, presets and agent adapters fit together when stacks composes a project, with examples from the default registry.
- Existing repositoryApply fragments such as CI, git hooks or agent guardrails to a repository you already have, without stacks overwriting any of your files.
- Write a stackTurn a project you trust into a stack or fragment in your user registry, validate it, preview its brief and test it with an agent build.
- CLI commandsEvery stacks command and subcommand, with its flags, defaults, JSON result schema, exit codes and examples.