stackbone init

stackbone init talks to the control plane, not to a running installation, so it takes no --agent. You must be signed in with stackbone login first: there is no offline init. --json prints the standard envelope, and the codes at the bottom are the shared exit codes.

stackbone init [dir] [--with empty|agent|workflow|workflow-agent]

Scaffold a new workspace. init is workspace-first and links the workspace to your organization: it registers the workspace's identity in the control plane and writes a .stackbone/project.json (so dev, link and the management commands know which org to talk to). Alongside the link it writes the workspace shell.

The shell is a multi-piece project:

a deep-agents/ folder (one agent per subfolder);
a workflows/ folder (one durable workflow per file), with its own package.json and tsconfig.json;
a root package.json and tsconfig.json, plus a pnpm-workspace.yaml that installs workflows/ as a package of the same workspace;
an .npmrc (a hoisted node_modules layout so the runtime resolves one copy of each shared dependency);
a .gitignore, a README.md, and an AGENTS.md and CLAUDE.md that brief your coding agent on the layout;
the Stackbone agent skills and the docs MCP server, for the coding agents you tick in the prompt.

--with chooses an optional first piece scaffolded on top of the shell:

`--with` value	What it adds
`empty`	The shell only.
`agent`	One agent under `deep-agents/<name>/`.
`workflow`	One durable workflow at `workflows/<name>.workflow.ts`.
`workflow-agent`	An agent and a workflow already wired to call it.

Every kind links the workspace, so all of them need you to be signed in.

Flag	Type	Default	Description
`[dir]` positional	string	derived	Target subdirectory for the workspace. Omit it and `init` creates a subdirectory named after the workspace slug.
`--with`	string	`empty`	First piece to scaffold: `empty`, `agent`, `workflow`, or `workflow-agent`.
`--name`	string	derived	Workspace name (and the default name of the first piece). Lowercased into a slug, capped at 32 characters.
`--yes` / `-y`	boolean	`false`	Skip interactive prompts.
`--json`	boolean	`false`	Emit the structured JSON envelope instead of the pretty UI.
`--force`	boolean	`false`	Overwrite existing files in the target directory.
`--agents`	string	prompt	Comma-separated coding agents to set up, e.g. `claude-code,cursor`. Skips the prompt. `--no-agents` sets nothing up. See coding agents.
`--install`	boolean	`true`	Install the workspace dependencies after scaffolding: `pnpm install` when pnpm is on `PATH`, `npm install` otherwise. `--no-install` skips it.

Starters are gone from init. Passing --starter or --template now prints a migration message and exits non-zero. Templates moved to a per-piece flag on add (stackbone add workflow <name> --template <t>).

Interactive prompts: init asks only when stdin is a terminal, CI is not set in the environment, and you passed neither -y nor --json. It prompts for the workspace name when you gave neither [dir] nor --name, shows a picker of the --with kinds (empty, agent, workflow, workflow-agent), and ends with a checklist of coding agents to set up. Any other run takes the derived name and --with empty, and sets up no coding agents unless you pass --agents.

Dependency install: after the files are written, init runs the first install in the workspace, with pnpm when pnpm --version answers on PATH and npm otherwise. The scaffold works the same with either (its .npmrc pins a hoisted node_modules layout). The install is best-effort: a failure prints the package manager's last lines as a warning, the command still exits 0, and the Next steps note keeps the <pm> install line for you to run. --no-install skips the step, and then the note names pnpm install.

JSON payload

{
  "schema_version": 1,
  "workspace": { "name": "acme", "dir": "/abs/path" },
  "with": "agent", // the --with value
  "files_written": [
    /* every file written, sorted alphabetically */
  ],
  "agent": { "id": "...", "slug": "...", "name": "..." }, // the workspace's own control-plane identity
  "local_dev_installation": { "id": "...", "organization_slug": "..." },
  "agent_setup": {
    "ok": true,
    "selected": ["cursor"], // the coding agents you ticked, or []
    "steps": {
      "skills": "ok", // "ok" | "failed" | "skipped"
      // One entry for EVERY supported agent, always. The ones you did not tick read "skipped".
      "mcp": { "claude-code": "skipped", "cursor": "written" /* … */ },
    },
  },
  "dependencies": {
    "status": "installed", // "installed" | "failed" | "skipped"
    "package_manager": "pnpm", // "pnpm" | "npm" | null (null when skipped)
    // "error": "…" (present only when status is "failed")
  },
}

agent and local_dev_installation describe the workspace's own control-plane registration, the single identity every --with kind shares.

Exit codes: 0 ok, 2 auth (not signed in), 1 generic (a file collision without --force, an unknown --with value, or a removed --starter / --template flag).

Next: grow the workspace with stackbone add, then run it with stackbone dev.