Polyglot Lifecycle Orchestration

workspace run is Workspai's governed fleet-execution surface. It discovers the runtime units inside registered projects and can run init, test, build, start, or a custom stage declared in .workspai/context.json.

It is intentionally separate from workspace intelligence run. The intelligence runner produces the canonical model, graph, governance evidence, verification verdict, context, and agent grounding. Lifecycle orchestration executes project commands and publishes the evidence those gates can require.

Plan before execution

Start with a machine-readable plan:

npx workspai workspace run build --plan --json
npx workspai workspace run test --runtime rust --plan --json

Planning returns each selected runtime unit, its root, manifest, role, stage, and command without executing it. Doctor and Readiness gates are skipped during plan-only mode because no project command is being run.

A polyglot project can expose several bounded runtime units—for example a Node package, a Cargo crate, a Go module, or a CMake/Meson native build. --runtime limits the plan and execution to one detected runtime family. Vendored trees, build outputs, and nested fixtures are excluded from lifecycle discovery.

Select the smallest useful fleet

npx workspai workspace run test --scope project:api --json
npx workspai workspace run test --affected --since HEAD~1 --json
npx workspai workspace run test --affected --blast-radius --strict --json

• --scope project:<name> selects one registered project.
• --affected selects projects changed since the Git reference.
• --blast-radius expands that set through dependency and event relations.
• --runtime <family> selects matching units inside polyglot projects.

Selection is explicit in the JSON report. A project outside the selected scope, not affected by the change, or stopped after an earlier failure remains visible as skipped with a reason; it is not counted as a successful execution.

Execute with governed gates

npx workspai workspace run test --parallel --max-workers 4 --strict --json
npx workspai workspace run build --reuse-passed --json
npx workspai workspace run start --scope project:api --json

Real test, build, and start runs enforce Doctor workspace and Readiness pre-run gates by default. A failed gate prevents selected project commands from running and records which gate blocked execution. init and plan-only mode do not enforce those gates. --no-gates is an explicit operator override, not a claim that the workspace is healthy.

Always inspect gates.blocked in JSON. Add --strict when a failed or warning gate must also produce a non-zero process exit; non-strict mode preserves the structured gate result without promoting advisory policy to process failure.

Use --parallel with --max-workers for bounded concurrency, --continue-on-error when later projects should still run, and --reuse-passed only when reusing a compatible passed stage from the existing workspace-run evidence is acceptable.

dev and stop are not fleet stages. dev is a long-running project-local primitive. Custom fleet stages must be declared in .workspai/context.json.

Read the evidence, not terminal prose

Every run publishes:

.workspai/reports/workspace-run-last.json

The report records selection mode, scope, graph expansion status, gate results, runtime executions, commands, duration, status, exit code, and bounded failure diagnostics. failureDiagnostic.outputExcerpt preserves the command context and terminal root cause without copying an unbounded log.

When Verify reports missing lifecycle evidence, its blocker-resolution hint can name the exact sourceCommand to run and the exact sourceArtifact to refresh. Consumers should execute that producer once, then verify again. They should not guess a replacement command from the artifact filename.

How it fits the architecture

workspace run does not insert a twelfth stage into the canonical Intelligence chain, and workspace verify does not rerun an arbitrary lifecycle command on the consumer's behalf. This separation keeps execution, evidence production, and acceptance decisions inspectable.