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 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 AGENTS.md and .workspai/reports/INDEX.json, query the Knowledge Graph with workspace graph search <query> --limit 12 --json (or MCP searchWorkspaceGraph), follow proof paths, and expand to the full 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,
AGENTS.md,
Copilot instruction files,
Cursor rules,
Claude files,
generated skills,
MCP evidence design.

The runner's --for-agent value and agent-sync targets are related but not identical contracts. Use generic, codex, claude, cursor, or orca to label the bounded context pack. Use workspace agent-sync --target ... to project that evidence into integration files. Its accepted contract values are all, vscode, agents, copilot, cursor, claude, codex, and 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.