> [Agent navigation index](/llms.txt)

# Workspace workflows and deployment

Run complete or focused lifecycle commands, build applications independently, and diagnose workspace ownership and installation.

Run these commands from a workspace created as described in [workspace architecture](/docs/workspaces-libraries.md).
You should have one root lockfile and direct `workspace:*` links before relying on root orchestration.

Workspace link and adoption commands check existing workspace-health blockers before installation,
including in `--dry-run`. Repair unrelated member errors first; a successful preview is not an install
or a guarantee against later failures. Adoption permits the target manifest and nested lockfile issues
that it is responsible for migrating, then diagnoses the resulting workspace transactionally.
For missing member environment types, root doctor reports a scoped repair such as
`brix env#apps/backend types`; plain `brix env types` requires an application directory.

## Run root workflows

From the workspace root:

```sh
brix install
brix dev
brix check
brix test
brix build
brix ci
brix verify

```

`brix dev` runs development projects in parallel. Check, test, build, and verify preserve library dependency order and skip an external member's missing phase scripts. `brix ci` performs the clean, lockfile-exact root installation, reconciles project-pinned skills, and fails if any member application's committed `src/env.generated.d.ts` is stale; it runs no checks, tests, or builds. `brix verify` is the complete diagnosis, check, test, and build gate for an installed workspace. Both run only at the workspace root.

Root `brix check`, `brix format`, and `brix verify` process ordinary root-owned files separately
from member trees. Member phase scripts own their files, including custom supported Oxc configs;
external members keep their framework's scripts. The root Oxc pass does not override member policy
or format an external application's files when its format script is absent.

## Select one project

Select a unique member by basename, package name, or path:

```sh
brix doctor#checkout-bff
brix check#commerce-contracts
brix test#checkout-bff --project node
brix build#apps/checkout-bff
brix start#checkout-bff

```

An existing workspace-relative test path selects its owner automatically:

```sh
brix test apps/checkout-bff/src/features/checkout/route.test.ts -t "returns checkout"
brix test apps/checkout-bff/e2e/checkout.spec.ts -t "places an order"

```

A selection spanning multiple members is rejected. Focused node tests do not run the root Storybook catalog or provision browsers. Focused commands build only the selected member's upstream libraries that need build output (see [Library source and build output](/docs/workspaces-libraries.md#library-source-and-build-output)), so starting one member never rebuilds a library that only another member reads. These builds replace `dist` files in place rather than cleaning first, so running members that read them are not interrupted.

Focused `dev` of an application or external project, including plain `brix dev` inside it, runs
the member together with watchers for the libraries it reads as build output, such as a Panda
design system or a library an external application imports. Library edits reach the running member
without a restart; libraries it compiles from source need no watcher.

Focused library `build` and `dev` first build that library's upstream libraries that need build
output, in dependency order, using their build scripts. They do not rebuild the selected library
during preparation or build unrelated libraries. The same applies to plain commands inside the
member. In library `dev`, preparation runs once before the selected library's watcher starts; use
root `brix dev` to watch upstream libraries at the same time.

Workspace lookup stops at a nearer standalone `pnpm-workspace.yaml` or foreign workspace
declaration. An independently installed tool nested in another repository does not inherit an outer
Brix workspace's tools or Storybook sources. Keep real workspace members on the shared root install.

A project is a member only when the nearest Brix workspace's `package.json#workspaces` patterns
select it; `init`, `doctor`, `create`, lifecycle commands, and the launcher share that rule.
`node_modules` directories are never members, and the launcher accepts `*`, `**`, `?`, and `{a,b}`
patterns, rejecting other glob syntax instead of guessing. Keep `pnpm-workspace.yaml#packages`
identical to `package.json#workspaces`: `brix init` rewrites it from the manifest and `brix doctor`
reports drift. A member must not declare its own `pnpm-workspace.yaml` or nested `workspaces`;
doctor reports either, and move required settings and catalog entries to the root before deleting
the member file. Creating a project at a path selected by the workspace patterns makes it a
member even when you run `brix create` from a non-member directory such as `apps/`.

## Build and deploy independently

Build all projects from one revision with `brix verify`, or focus an application in its deployment pipeline:

```sh
brix build#checkout-bff
PORT=3000 brix start#checkout-bff

```

Deploy each application's own output and runtime configuration. Applications can deploy the same repository revision on different schedules, but one workspace intentionally shares one Brix version and lockfile. Projects requiring incompatible framework versions belong in separate workspaces.

## Diagnose the workspace

```sh
brix inspect workspace --json
brix doctor --json
brix ci
brix verify

```

Confirm one root lockfile, direct `workspace:*` links, no application-to-application dependencies, unique package names and basenames, and separate output for every deployable member. Member `node_modules` directories may exist as part of the one root-managed isolated installation; members must not own nested lockfiles or standalone installs.

Continue with [Storybook](/docs/storybook.md), [publishing releases](/docs/releases-publishing.md), and [CLI commands](/docs/cli.md).
