AI Does Not Need More Code. It Needs a Workspace Contract.

An AI coding assistant can read a controller, explain a function, and generate a reasonable patch. It can still be wrong about the system.

The missing information is often not hidden in another source file. It is spread across the workspace:

• the API contract says one thing while the implementation says another;
• a service imports a package that is not declared in the expected place;
• the code is valid, but the selected workspace profile forbids the runtime;
• a deployment file exposes a different port;
• the report the agent trusted was generated before the latest change;
• the change is locally safe but blocks release readiness elsewhere.

More source code does not resolve all of those questions. The assistant needs a shared description of the system and a way to prove where that description came from.

That is the job of a workspace contract.

A repository is not the whole decision boundary

Most code intelligence begins with a repository:

That view is useful. It can answer where a function is defined or which module imports another module.

An engineering decision usually crosses more boundaries:

workspace
├── projects
├── service contracts
├── runtime policies
├── dependencies
├── infrastructure
├── documentation
├── generated evidence
└── release gates

Suppose an agent is asked to change a login endpoint. Reading the controller is not enough. A safe answer may depend on an OpenAPI schema, a frontend consumer, an environment variable, a database migration, a CI check, and a decision record in another project.

The unit of understanding is no longer one file. It is the workspace.

What a workspace contract does

A workspace contract is a machine-readable operational map. It identifies the workspace, its registered projects, their locations, and the relationships that other intelligence operations are allowed to observe.

In Workspai, the contract lives at:

.workspai/workspace.contract.json

It is not a hand-written description that slowly drifts away from reality. Workspace commands synchronize and verify it against observable project state.

The contract does not need to contain every fact about every symbol. It needs to establish a stable boundary and identity layer:

• which projects belong to this workspace;
• which projects are linked, imported, or created here;
• where their metadata lives;
• which declared ports, APIs, and dependencies are part of the operational picture;
• which evidence can be refreshed and verified.

That gives every downstream consumer the same starting point.

Start with software you already have

You do not need to restructure an existing project to put it under Workspace Intelligence.

From the project directory:

npx workspai adopt . --json

adopt keeps the source in place. When the project is not already inside a Workspai workspace, the CLI creates or reuses a managed minimal workspace in the default Workspai location, registers the project, and returns the workspace path and a suggested cd command.

Continue from that workspace directory:

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

Adoption is an ingestion route, not an intelligence result. It tells Workspai what can be observed. The intelligence chain then builds and checks the current evidence.

The contract is the beginning, not the answer

A contract alone can also be stale or incomplete. Workspai therefore does not treat “a JSON file exists” as proof that the workspace is healthy.

The canonical chain runs eleven stages in a fixed, contract-backed order:

Sync and baseline resolution happen around the chain as two recorded preflight operations: Sync runs before Model, while baseline resolution happens after Model and before Diff. They do not become invented extra stages.

Each stage answers a different question:

• Model: What does the workspace look like now?
• Diff: What changed from the selected baseline?
• Impact: What might that change affect?
• Doctor evidence: Are the toolchains and project surfaces operational?
• Contract evidence: Does the workspace satisfy its declared contracts?
• Analyze evidence: What quality and policy findings are present?
• Readiness evidence: Is there evidence that blocks a release decision?
• Verify: Do the required evidence and contracts agree?
• Context: What should an agent receive for this task?
• Agent sync: Which governed agent surfaces must be updated?
• Explain: How can the result be communicated with traceable evidence?

The value is not the number of commands. The value is that every consumer sees the same order and the same decision boundary.

Model first, graph second

It is tempting to make the graph the source of truth. Workspai deliberately does not.

The canonical direction is:

The graph is a powerful representation for relationships and traversal. The model remains the technology-neutral description of the workspace.

This separation matters. A user can render the same model as JSON, a graph, a diagram, or an agent context without making the meaning of the workspace depend on one graph database or renderer.

What the agent gains

Without a shared contract, an agent has to rediscover the workspace during each task. It searches folders, guesses which reports matter, and may attach fresh confidence to stale evidence.

With a contract-backed model, the agent can begin with sharper questions:

• Is this project registered?
• Is the supporting artifact fresh?
• Which relationship proves the suspected impact?
• Is the failure local, or is it a release blocker?
• Which producer command owns the stale artifact?
• Did the repair change source state, or only regenerate a report?

This does not make the agent infallible. It makes its decisions inspectable.

What this does not mean

A workspace contract is not:

• a replacement for tests;
• a promise that every framework has a native generator;
• permission for an agent to bypass credentials or approval boundaries;
• a complete universal call graph;
• evidence that a workspace is healthy merely because the file exists.

Any readable project can enter through adoption or import when it can be registered. Runtime detection improves how deeply Workspai understands the project; it is not a closed permission list.

The practical shift

The old question was:

How much code can the model read?

The more useful question is:

Which decision can the model justify from current workspace evidence?

That shift changes what we build. Instead of collecting a larger prompt, we establish a shared operational boundary, derive a model, preserve proof, and make the result available to people, CI, IDEs, MCP clients, and agents.

The workspace contract is not the intelligence itself. It is the agreement that makes reliable Workspace Intelligence possible.