Agent Grounding

How Workspai aligns Copilot, Cursor, Claude, Codex, MCP clients, and other agents around the same evidence.

Agent Grounding is the process of giving AI tools the same scoped workspace truth that developers and CI use.

It does not make agents deterministic. It gives them a stronger operating contract.

Problem

Without grounding, every AI tool starts by rediscovering the repository:

Ungrounded agent failure cycleLocal rediscovery without governed evidence compounds uncertainty instead of producing a shared system view.

Workspai path

Workspai generates agent-facing artifacts from the Workspace Intelligence layer:

Agent-grounding projectionAgent surfaces are projections of the same workspace model and context, not independent sources of truth.

Current commands

npx workspai agent bootstrap --for-agent generic --strict --json
npx workspai workspace context --for-agent --json --write
npx workspai workspace agent-sync --write --refresh-context --preset enterprise
npx workspai workspace mcp serve

For knowledge retrieval, do not begin by loading every report or rescanning the repository. Start with the project-local .workspai/agent-entry.v1.json and AGENTS.md, verify the bootstrap receipt, then read the workspace report index, active Goal or handoff, compact context, relevant operational Skills, and a task-scoped Graph query. Follow proof paths and expand to live source or the complete model only when the bounded answer is insufficient.

Agent graph projections carry an omission budget with limits and explicit omitted counts. A client must preserve that budget in its handoff: truncated means the result is a bounded evidence window, not that no other matching entities, relations, or proofs exist.

Generated surfaces

Depending on command options and workspace state, agent grounding can include:

.workspai/reports/workspace-context-agent.json,
.workspai/reports/agent-customization-pack.json,
.workspai/reports/INDEX.json,
.workspai/AGENT-GROUNDING.md,
project-local .workspai/agent-entry.v1.json,
.workspai/reports/agent-bootstrap-receipt.json,
AGENTS.md,
Copilot instruction files,
Cursor rules,
Claude files,
runtime-aware generated Skills,
MCP evidence design.

The runner's --for-agent value and agent-sync targets are related but not identical contracts. Current projections cover generic/AGENTS.md, VS Code and Copilot, Cursor, Claude, Codex, Gemini, Qwen, Kimi, Grok, Windsurf, and Amazon Q surfaces. Use workspace agent-sync --target ... to select a projection or all to reconcile every supported host. Authored instructions and Skills are preserved; only Workspai-owned blocks and projections are regenerated.

The exact current target values are all, vscode, agents, copilot, cursor, claude, codex, gemini, qwen, kimi, grok, windsurf, amazon-q, and the compatibility alias orca.

Answer contract

Agent-facing output should follow a disciplined shape:

Evidence-backed agent answer contractThe answer preserves scope, diagnosis, execution, verification, and unresolved assumptions as distinct stages.

This keeps the agent tied to workspace evidence instead of free-form guessing.

For repairs, the same rule applies to authority. A model may inspect evidence and propose source edits, but the CLI Repair Engine owns plan validation, approval binding, checkpointing, mutation, verification, rollback, and terminal closure; a chat or IDE is not a second mutation authority. It must not report success while the CLI transaction is open, rolled back, or decision-required.

Boundary

Workspai does not claim that an AI agent is forced to obey every instruction. The claim is narrower and stronger: grounding artifacts make the desired behavior explicit, versioned, inspectable, and easier to audit.