Guides
Practical Workspai workflows for existing repositories, new projects, agent grounding, and release gates.
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.
npx workspai adopt /path/to/project --json
npx workspai workspace model --json --write
npx workspai workspace context --for-agent --json --write
npx workspai workspace verify --strict --jsonWhat happens:
- the project is registered,
- runtime signals are observed,
- model and context are generated,
- verification can evaluate the 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 model --json --writeThe 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 enterpriseWhat 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 diff --from git --json --write
npx workspai workspace impact --from .workspai/reports/workspace-model-diff-last-run.json --json
npx workspai workspace verify --strict --json
npx workspai pipeline --json --strictRelease readiness should be backed by evidence, not vibes.
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 --writeThe goal is a narrative that still points back to generated evidence.