Guides

These guides are intentionally short. Each workflow should show the architecture loop: input, model, evidence, consumer.

Adopt an existing repository

Use this when a project already exists.

cd /path/to/project
npx workspai adopt . --json
npx workspai workspace intelligence run --for-agent generic --strict --json

What happens:

• outside an existing workspace, a managed minimal workspace is created or reused,
• the project is linked and registered without moving its source,
• portable project grounding and a bounded context lens are written,
• a gitignored machine-local link lets commands resolve the governing workspace from the project directory,
• runtime signals are observed,
• the complete model, change, evidence, verification, and grounding chain runs,
• strict verification blocks incomplete or warning-level workspace state.

Start from a supported kit

Use this when Workspai owns the create path for the requested kit.

npx workspai my-workspace --yes --profile polyglot
cd ~/.workspai/workspaces/my-workspace
npx workspai create project nextjs web --yes
npx workspai create project fastapi.standard api --yes
npx workspai workspace intelligence run --for-agent generic --json

The scaffold is useful, but it is not the whole product. The larger value is the workspace model and evidence loop around the project.

Ground AI tools

Use this before asking an AI tool to reason about the system.

npx workspai workspace context --for-agent --json --write
npx workspai workspace agent-sync --write --refresh-context --preset enterprise

What gets aligned:

• workspace context,
• report index,
• AGENTS.md,
• IDE-specific surfaces,
• skills,
• MCP-ready evidence design.

Gate a release

Use this when a change must be evaluated before merge or release.

npx workspai workspace intelligence run --for-agent generic --strict --json

This is the canonical Workspace Intelligence gate. It preserves dependency order and evidence coherence, and succeeds only when its required evidence is ready.

When the broader governance and release workflow is required, run it as a separate orchestration boundary:

npx workspai pipeline --json --strict

pipeline does not extend or reorder the canonical intelligence chain. Release readiness should be backed by evidence, not vibes.

Run a polyglot lifecycle stage

Inspect runtime units before executing commands across a mixed workspace:

npx workspai workspace run test --plan --json
npx workspai workspace run test --runtime rust --scope project:native-api --json

The plan is non-executing. The real run is governed by Doctor and Readiness gates and writes .workspai/reports/workspace-run-last.json. See Polyglot Lifecycle Orchestration for affected selection, blast radius, concurrency, cache reuse, and failure semantics.

Keep a larger request measurable

Use a Verified Engineering Goal when the work may span multiple fixes or agent sessions. Planning creates the durable finish line; it does not claim the work is already complete.

# Prepare the whole workspace for release.
npx workspai workspace goal plan release-readiness --json

# Repair one project's blocking dependency vulnerabilities without silently
# authorizing forced or breaking changes.
npx workspai workspace goal plan dependency-security --scope project:api --json

# Raise one project's measured coverage to 75%.
npx workspai workspace goal plan test-coverage --scope project:web --target 75 --json

Keep the returned goal ID. A user, CI job, IDE, or agent can inspect and verify that same objective later:

npx workspai workspace goal status <goal-id> --json
npx workspai workspace goal verify <goal-id> --json

For dependency security, Workspai does not accept a manifest edit as the final result. The affected project must reconcile its manifest and lockfile, rerun the focused audit, pass declared tests and build, and then pass the canonical workspace verification. High-risk choices stay visible unless the goal explicitly permits them.

Explain a blocker

Use this when a human or agent needs the reason, not only the exit code.

npx workspai workspace explain release-blocked --json --write
npx workspai workspace trace --from .workspai/reports/workspace-model-diff-last-run.json --json --write

The goal is a narrative that still points back to generated evidence.