Skip to content
stacks
Docs menu

Start a new project

Choose a stack, adjust its fragments and preset, preview the result, and write a full project your agent builds to a green verify.

View as MarkdownOpen in ClaudeOpen in ChatGPT

This guide uses stacks new to write a project you intend to ship. It uses the default preset, so you answer the stack's decisions yourself.

Find and inspect a stack

Search in plain words, then read the candidate in full:

stacks search "Python API with Postgres" --kind stack
stacks show python-api
Terminal

show lists the stack's decisions, its fragments and its verify steps. The Tools line lists programs that need to be on your PATH by the time your agent builds. stacks warns about a missing one and never fails because of it.

If two stacks fit, stacks search --json and stacks show --json carry the evidence behind each: the date of the last recorded agent build that passed, and published project stats when they exist. How search ranks entries explains the fields.

Choose a preset

A preset decides how much the agent asks and what gets included:

Preset Decisions Deploy and release fragments Steps tagged prod
default The agent asks you each one Included when the stack defaults to them Run
sandbox The agent takes every default Left out unless you name them with --with Skipped unless you run verify --all

default applies when you pass no preset flag and suits a project you'll ship. --sandbox is for trying a stack locally.

If you want the defaults without the sandbox restrictions, add --yes. The brief then tells the agent to take each decision's default and list what it chose in its summary.

Add and remove fragments

A stack's fragments are required, default or optional. Required fragments are always included, default fragments are included unless you pass --without, and optional fragments are included only when you pass --with.

stacks new go-cli my-cli --with goreleaser --without ci-github --dry-run
Terminal

--with and --without are repeatable and take comma-separated lists. A fragment can require another, which is then pulled in for you, and two fragments can conflict, in which case new exits 2 with ComposeConflict and names the --without flag that resolves it.

stacks list fragments shows every fragment. stacks show <fragment> tells you what it adds and which stacks it applies to.

Add an app

An app is a fragment that adds a working feature on top of a stack, where other fragments add infrastructure. react-router offers openrouter-chat, which turns the bare project into a streaming chat app:

stacks new react-router my-chat --with openrouter-chat
Terminal

Apps are left out of sandbox projects unless you name them. Their verify steps run as a second stage, after the base project passes. stacks list apps shows which apps exist and which stacks they fit.

Preview with --dry-run

--dry-run composes the project, renders every file in memory and stops:

stacks new go-cli my-cli --dry-run
Terminal
Planned my-cli from go-cli.
Fragments: agent-ops, ci-github, git-hooks
Agents: claude
Git: would create a new repository
...
Brief: .stacks/BRIEF.md (3271 words)
Dry run: nothing was written.
Output

It creates no directory, state record or git repository, and starts no agent. Run it whenever you change fragments to check the file list and the brief size before anything is written.

To read the brief a composition produces without writing a project, use validate --brief:

stacks validate --brief go-cli --with goreleaser
Terminal

Set the directory and project name

The directory argument is optional. Without it, the project goes in ./<stack>, or in the slug of --name when you give one.

stacks new typescript-cli --name "Acme Deploy" --author "A. Name" --scope acme
Terminal

That writes ./acme-deploy. Starter files ending in .tmpl get these values filled in: --name becomes the project name, --author the author (falling back to your git user.name), and --scope the npm scope for package names.

The target directory must be missing or empty. A directory holding only .git and OS files such as .DS_Store counts as empty. Anything else fails with TargetNotEmpty (exit 2), and nothing is written.

Write the project and launch the agent

stacks new go-cli my-cli
Terminal

new writes the files, runs git init when the target isn't already inside a repository, and launches your agent. With the default preset, the agent starts by asking you the decisions listed in the brief. Answer them, then let it work.

If anything fails or you press Ctrl+C partway, new removes everything it wrote.

Warning

Inside another repository, stacks doesn't run git init, and it refuses fragments that need their own repository, such as ci-github and git-hooks, which configure the repository root. Write the project somewhere else, or drop the fragment with the --without flag the error names.

Commit the manifest

Commit .stacks/manifest.json. It records the fragments and verify steps, so anyone who clones the repository can run stacks verify and get the same checks. The brief, the notes and the run history are git-ignored by the .stacks/.gitignore that new writes.

On a fresh clone there's no state record on that machine, so verify checks the steps against the manifest's copy only and says so in its result. Verify has the details.

Save defaults in config.json

Flags you repeat on every project can go in ~/.config/stacks/config.json:

{
  "agents": ["claude", "codex"],
  "always": ["git-hooks"],
  "author": "A. Name",
  "package_scope": "@acme",
  "preset": "sandbox"
}
~/.config/stacks/config.json

always adds fragments to every project they fit; --without still removes one. Flags override the file. Configuration lists every key.

Next steps