---
title: 'add'
description: 'Add one agent or one durable workflow to a workspace you already created.'
position: 7
---

# stackbone add

> `stackbone add` only writes files on disk. It runs offline, never contacts the
> control plane and needs no login, so it takes no `--agent`.
> `--json` prints the [standard envelope](/docs/cli/reference/conventions#json-output),
> and the codes at the bottom are the
> [shared exit codes](/docs/cli/reference/conventions#exit-codes).

```sh
stackbone add agent|workflow|workflow-agent <name>
```

Add one new piece to an existing workspace. `add` **only writes new files**: it
never edits your existing TypeScript and never edits `stackbone.config.ts`. A
name collision fails; re-run with `--force` to overwrite. You
must run `add` **inside a workspace**. Every kind runs **offline**: a piece
you add joins the workspace [`init`](/docs/cli/reference/init) already linked,
so it gets no control-plane registration of its own and requires no login.

The file convention decides where each piece lands and how the runtime finds it
again. See
[What a Stackbone project is](/docs/cli/reference/commands#what-a-stackbone-project-is).

```bash
stackbone add agent support
stackbone add workflow nightly-digest
stackbone add workflow qualify-lead --calls lead-qualifier
stackbone add workflow-agent lead-qualifier
```

## stackbone add agent

`stackbone add agent <name>` (alias of `add deep-agent`) scaffolds one
agent under `deep-agents/<name>/index.ts`. Agents carry no per-piece manifest:
their runtime dependencies (the agent-authoring library and its model
provider packages) merge into the workspace root `package.json`, adding only
the ones not already pinned there.

| Flag      | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| `--yes`   | boolean | Accepted for consistency. `add` never prompts. |
| `--json`  | boolean | Emit the structured JSON envelope.             |
| `--force` | boolean | Overwrite files on a name collision.           |

**JSON payload**

```jsonc
{
  "schema_version": 1,
  "kind": "deep-agent",
  "name": "support",
  "target_dir": "/abs/path", // the workspace root
  "files_written": [
    /* the new files, RELATIVE to the workspace root, sorted (e.g. "deep-agents/support/index.ts") */
  ],
  "registered_in_config": false,
  "deps_added": [
    /* runtime deps newly merged into the workspace root package.json, if any */
  ],
  "control_plane_agent": null,
}
```

## stackbone add workflow

`stackbone add workflow <name>` adds one durable workflow file at
`workflows/<name>.workflow.ts`. It **never touches the control plane**
(durable workflows are dev-only today). `--calls <agent>`
wires a step inside the workflow that delegates a turn to that agent (the
workflow → agent hybrid).

| Flag         | Type    | Description                                         |
| ------------ | ------- | --------------------------------------------------- |
| `--template` | string  | Template id: `default` or `approval`.               |
| `--calls`    | string  | Agent name to delegate a turn to from the workflow. |
| `--yes`      | boolean | Accepted for consistency. `add` never prompts.      |
| `--json`     | boolean | Emit the structured JSON envelope.                  |
| `--force`    | boolean | Overwrite files on a name collision.                |

Both template ids scaffold the same minimal workflow today, and any other value
fails. `--calls` changes the file you get.

**JSON payload**

```jsonc
{
  "schema_version": 1,
  "kind": "workflow",
  "name": "nightly-digest",
  "target_dir": "/abs/path", // the workspace root
  "files_written": ["workflows/nightly-digest.workflow.ts"],
  "registered_in_config": false,
  "control_plane_agent": null,
}
```

## stackbone add workflow-agent

`stackbone add workflow-agent <name>` is the composed template: it scaffolds
an agent **and** a workflow already wired to call it (the
`qualify-lead` → `lead-qualifier` pattern). It merges the same runtime deps as
`add agent`, and the JSON `kind` is `"workflow-agent"`.

It takes the same flags as `add agent` (`--yes`, `--json`, `--force`), and no
`--template`.

## Exit codes

The same for all three kinds: `0` ok, `3` no project (`add` run outside a
workspace), `1` generic (a name collision without `--force`, a name that is not
a lowercase kebab slug, or an unknown `--template`).