Add to an existing repository

# Add to an existing repository

> Apply fragments such as CI, git hooks or agent guardrails to a repository you already have, without stacks overwriting any of your files.

`stacks add` applies fragments to a repository you already have. It never overwrites a file: where your project already has one, stacks parks its version for your agent to merge, and `verify` then checks the whole project.

## Find a fragment

A fragment is one capability, such as GitHub Actions CI, lefthook git hooks, Postgres, or agent guardrails. List them with their categories:

```sh title="Terminal" group="list"
stacks list fragments
```

```text title="Output" group="list"
Fragments
  agent-ops            agent-ops
    ...
  ci-github            ci
    ...
  docker-deploy        deploy
    ...
  git-hooks            tooling
    ...
  postgres             service
    ...
```

Each row has a one-line description under it (trimmed here). Read one in full before adding it:

```sh title="Terminal"
stacks show ci-github
```

`show` prints what the fragment adds, the stacks or tags it applies to, the files it ships and the verify steps it brings. Some fragments only fit certain stacks; `postgres`, for example, applies to the Python stacks.

## Run `stacks add`

From the repository root:

```sh title="Terminal"
stacks add ci-github git-hooks
```

Or point at another directory with `--dir`:

```sh title="Terminal"
stacks add agent-ops --dir ../my-project --no-launch
```

`add` applies the fragments you named and any fragments they require, writes `.stacks/BRIEF.md` describing the work, and hands off to your agent the same way `new` does. It runs no install and no verify steps itself.

## Files your project already has

For each file a fragment ships, `add` checks whether your project already has it:

| The project already has the file? | What `add` does |
| --- | --- |
| No | Writes it |
| Yes, with the same bytes | Skips it |
| Yes, with different content | Leaves yours alone and parks its version under `.stacks/incoming/<path>` |

`agent-ops` ships an `AGENTS.md`, for example. Add it to a repository that already has one and your `AGENTS.md` stays as it is, while stacks writes its version to `.stacks/incoming/AGENTS.md`.

The brief lists every parked file and asks the agent to merge each one while keeping your project's choices, then delete it from `incoming/`. If you run `add` again before the merge is done, the brief lists the pending files from earlier runs as well.

Many fragments ship few files or none, because the brief tells the agent what to write with current tools. `ci-github` describes the workflow and the agent writes it.

## The manifest `add` writes

The first `add` in a repository creates `.stacks/manifest.json` with `mode: "add"` and no stack. It takes the project name from `package.json`, `pyproject.toml`, `go.mod` or `Cargo.toml`, falling back to the directory name. The manifest records the fragments and the verify steps they bring.

On later runs, `add` keeps what's already there: the preset, the agent targets, the accepted verify steps and any commands and environment values you set. `--sandbox` and `--agents` only apply when `add` creates the manifest; passing a different value on an existing project is refused.

Commit the manifest. The brief, notes and run history stay git-ignored.

## What the agent does after `add`

Once the brief is written, the agent:

1. Reads `.stacks/BRIEF.md`.
2. Merges each file under `.stacks/incoming/` into the real one, keeping your project's choices.
3. Runs `stacks verify` over the whole project and fixes what fails until it's `green`.

If you started with `--no-launch`, open the repository in your agent and ask it to read `.stacks/BRIEF.md` and carry it out.

> [!NOTE]
> verify runs every step in the manifest, including the ones your project had before this `add`. If your project was already failing its lint, the agent will be fixing that too.

## Adding to a project that already has a manifest

In a project that already has a manifest, plain `stacks list` shows only the fragments that fit it and haven't been applied, each with its `add` command:

```sh title="Terminal" group="addable"
stacks list
```

```text title="Output" group="addable"
Fragments you can add
  ce-plugin
    ...
    Next: stacks add ce-plugin
  goreleaser
    ...
    Next: stacks add goreleaser
  rr
    ...
    Next: stacks add rr
```

That output is from a `go-cli` project.

Before planning anything, `add` checks the existing verify steps the same way `verify` does. If they've been changed since they were recorded, `add` refuses with `VerifyChanged` (exit 5) until you accept or undo the change.

## Next steps

- [Use stacks with your agent](https://stacks.steamfield.io/docs/agents.md): let the agent pick fragments and run `add` itself.
- [The brief and the manifest](https://stacks.steamfield.io/docs/concepts/brief-and-manifest.md): what's in each file and who may edit it.
- [CLI commands](https://stacks.steamfield.io/docs/reference/commands.md#stacks-add): every flag of `stacks add`.