Your AI Read Every File. It Still Missed the System.

Workspai.com — Sat, 25 Jul 2026 14:07:29 +0000

Imagine Alex has an existing Next.js project here:

/home/alex/code/storefront-web

An AI agent can read that entire folder and still miss the API it calls, the
workspace policy it must follow, or the evidence a release check considers
current. Giving the agent more files makes the prompt larger. It does not tell
the agent where the system boundary is.

We will connect storefront-web to a Workspai workspace without moving or
copying its source. Then we will generate a shared model, a proof-backed graph,
and focused agent context.

There are two easy ways to do it:

Your situation	Best path
You want the fastest setup for one existing project	Run `adopt` and let Workspai create or reuse its managed minimal workspace
You want to choose the workspace name and location	Create the workspace first, then adopt the project with `--workspace`
You want a copy of the project inside the workspace	Use `import` instead of `adopt`

We will use the second path first because it makes every location visible.

Prerequisites

Node.js and npm available
an existing project at /home/alex/code/storefront-web
a parent directory where Alex wants to keep the workspace

Replace /home/alex with your own home directory. The commands use $HOME so
you can copy them without hard-coding a username.

Path A: create a workspace where you want it

Alex wants this final layout:

/home/alex/code/storefront-web       existing source
/home/alex/workspaces/my-workspace   Workspai workspace

Create the workspace:

mkdir -p "$HOME/workspaces"
cd "$HOME/workspaces"
npx workspai create workspace my-workspace \
  --here \
  --profile minimal \
  --yes

--here creates the named workspace as a child of the current directory. For
Alex, the result is:

/home/alex/workspaces/my-workspace

It does not turn /home/alex/workspaces itself into a workspace.

If you prefer Workspai's managed location, omit --here:

npx workspai create workspace my-workspace --profile minimal --yes

That creates:

~/.workspai/workspaces/my-workspace

Adopt the existing project into that workspace

Now move into the existing project and link this project to the workspace
Alex just created:

cd "$HOME/code/storefront-web"
npx workspai adopt . \
  --workspace "$HOME/workspaces/my-workspace" \
  --name storefront-web \
  --json

Using . keeps the command easy to read: adopt the project in the current
directory, and register it in my-workspace.

A shortened result looks like this:

{
  "workspacePath": "/home/alex/workspaces/my-workspace",
  "workspaceResolution": "explicit",
  "suggestedCdCommand": "cd /home/alex/workspaces/my-workspace",
  "adoptedProject": {
    "name": "storefront-web",
    "path": "/home/alex/code/storefront-web",
    "relationship": "adopted"
  }
}

The important relationship is now explicit:

my-workspace
    └── links to /home/alex/code/storefront-web

Workspai does not create a second copy at
/home/alex/workspaces/my-workspace/storefront-web.

Instead, it writes project-side metadata such as:

/home/alex/code/storefront-web/.workspai/project.json
/home/alex/code/storefront-web/.workspai/adopt.json
/home/alex/code/storefront-web/.workspai/adopt-readiness.json

The workspace owns the shared contract, reports, policies, and agent outputs.
The project remains where Alex already develops it.

Path B: let Workspai choose the minimal workspace

If Alex is happy to use Workspai's default workspace, this is the complete
setup:

cd "$HOME/code/storefront-web"
npx workspai adopt .

That is all. Workspai detects the project name and stack, then creates or
reuses the managed minimal workspace:

~/.workspai/workspaces/workspai

The CLI prints the exact workspace path and the next cd command. The managed
workspace uses the minimal profile, while the source remains in
$HOME/code/storefront-web.

Add --json only when a script or another tool needs structured output. Add
--name storefront-web only when the detected project name is not the name you
want to register.

This route is useful when the immediate goal is simply:

Give my existing project a standard workspace boundary and make it readable
by agents.

The explicit path is better when several projects belong to one named product
or when a team wants to control where the shared workspace lives.

Continue from the workspace, not the project

For Path A:

cd "$HOME/workspaces/my-workspace"

For Path B, use the exact suggestedCdCommand returned by adopt.

This change of directory matters. Project commands can run from a project, but
commands that reason across the whole system should run from the workspace
boundary.

Build the shared understanding

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

generic keeps the example portable. Use a specific supported agent surface
only when you want agent-specific output.

In plain language, this command:

registers the current project inventory;
builds a canonical model of what Workspai can observe;
derives a relationship graph from that model;
checks health, contracts, impact, and readiness;
prepares current context and instructions for agents;
explains anything that still needs attention.

Don't worry if the first run does not end with a clean readiness result. A new
workspace may still have missing, stale, or conflicting evidence. Read the
reported blocker and follow the command that owns it; do not edit a generated
report just to make the warning disappear. The point of this run is to expose
what the workspace can prove now, not to manufacture a green status.

See what changed for Alex

After the run, the workspace contains a set of outputs with different jobs:

Output	What it tells Alex or an agent
`.workspai/workspace.contract.json`	`storefront-web` belongs to this workspace and where its source lives
`.workspai/reports/workspace-model.json`	The current projects, facts, evidence, and observed state
`.workspai/reports/workspace-knowledge-graph.json`	Relationships derived from the model, with supporting evidence
`.workspai/reports/workspace-context-agent.json`	Focused workspace context prepared for an agent
`.workspai/reports/INDEX.json`	The index of current reports, so consumers do not guess filenames
`AGENTS.md`	Portable grounding instructions for compatible agent workflows

The model is the canonical description of observed workspace state. The graph
is derived from it; a visualization or missing edge does not redefine the
workspace.

The result is not “AI understands everything.” It is more useful and more
honest:

Before:
agent → one project folder → guesses the wider boundary

After:
agent → workspace context → model → selected relationship → supporting evidence

When another project is adopted later—perhaps
/home/alex/code/storefront-api—the same workspace can describe both projects
and the evidence connecting them.

Give the agent focused evidence

The normal workflow does not require the user to run graph commands by
hand. The generated AGENTS.md and Agent Customization Pack instruct a
tool-enabled agent to begin with the report index and bounded graph retrieval
instead of reading the complete interchange graph or exploring every file.

After the API project joins the workspace, the agent can execute calls like
these through its shell or the equivalent MCP tools:

npx workspai workspace graph search "storefront user API" \
  --limit 12 \
  --json

npx workspai workspace graph evidence \
  "<returned-entity-id>" \
  --json

The second call uses an ID returned by the first. The agent should not invent
an endpoint label such as GET /users and assume it exists in every workspace.
If Workspai finds a match, the response includes stable IDs and proof
references that the agent can follow without loading every graph entity.

The commands are shown here so the behavior remains inspectable. In a normal
Agent workflow, the model performs this retrieval itself. A person only needs
to run them manually when using a chat surface that has no shell or MCP access,
or when independently auditing the agent's evidence.

An agent task can now be framed like this:

Use the current workspace context. Find the evidence connecting
storefront-web to the user API. Before editing, identify the affected
project and the contract that must remain compatible.

Without this evidence, an agent often starts with:

Which files seem related?

With a contract-backed workspace, it can ask:

Is the affected project registered?
Which current evidence supports this dependency?
Did the model change from the selected baseline?
Is the finding a warning or a blocker?
Which command owns the stale artifact?
Did a repair modify source, or only refresh a report?

Those questions do not guarantee a correct patch. They make the reasoning
inspectable and testable.

Which path should you choose?

Choose managed minimal adoption when:

you have one existing project;
you want the shortest route;
you do not care about naming a product-level workspace yet.

Create the workspace first when:

several projects belong to the same system;
you want a meaningful workspace name;
you want to choose its location or profile;
a team will share the same operational boundary.

Use import instead of adopt when the source should actually be copied or cloned
into the workspace.

Verify the exercise

storefront-web still exists at /home/alex/code/storefront-web.
Its .workspai/adopt.json identifies the adoption relationship.
The selected workspace contract contains storefront-web.
The workspace reports contain a current model, graph, context, and report index.
AGENTS.md exists at the workspace boundary.

Where to go next

Adopt a related API into the same workspace:

cd "$HOME/code/storefront-api"
npx workspai adopt . \
  --workspace "$HOME/workspaces/my-workspace" \
  --name storefront-api \
  --json

Return to /home/alex/workspaces/my-workspace, rerun Workspace Intelligence,
and query the relationship between the frontend and API.

That is where a workspace contract becomes more than metadata: it gives people,
CI, IDEs, MCP clients, and agents one operational definition of the system they
are changing.

Your turn

Think about the last “small” change that escaped its repository boundary.
Where did the missing fact live: another project, a contract, infrastructure,
CI, or an artifact nobody knew was stale?

That answer is a useful first test for any AI coding workflow. If the agent
cannot name that boundary before editing, reading more files may only make it
more confidently local.

Originally published on
Workspai.dev,
where this article is maintained as the canonical and up-to-date edition.

DEV Community: Chistiq