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, and the codes at the bottom are the shared exit codes.

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

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

{
  "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

{
  "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).