# 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.

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:

```sh title="Terminal"
stacks search "Python API with Postgres" --kind stack
stacks show python-api
```

`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](https://stacks.steamfield.io/docs/reference/search.md) 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`.

```sh title="Terminal"
stacks new go-cli my-cli --with goreleaser --without ci-github --dry-run
```

`--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:

```sh title="Terminal"
stacks new react-router my-chat --with openrouter-chat
```

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:

```sh title="Terminal" group="dry"
stacks new go-cli my-cli --dry-run
```

```text title="Output" group="dry"
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.
```

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`:

```sh title="Terminal"
stacks validate --brief go-cli --with goreleaser
```

## 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.

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

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

```sh title="Terminal"
stacks new go-cli my-cli
```

`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](https://stacks.steamfield.io/docs/concepts/verify.md#tamper-evidence) has the details.

## Save defaults in `config.json`

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

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

`always` adds fragments to every project they fit; `--without` still removes one. Flags override the file. [Configuration](https://stacks.steamfield.io/docs/reference/configuration.md) lists every key.

## Next steps

- [Verify: the definition of done](https://stacks.steamfield.io/docs/concepts/verify.md): phases, outcomes and why the agent can't edit the steps.
- [Write your own stack or fragment](https://stacks.steamfield.io/docs/guides/authoring.md): turn a project you trust into a recipe.
- [CLI commands](https://stacks.steamfield.io/docs/reference/commands.md#stacks-new): every flag of `stacks new`.