Skip to content
workspace.json workspace.json

workspace.json — open spec for codebase truth

OPEN SPECIFICATION · v0.4 · Apache 2.0

An open spec for what is true
about your code, right now.

workspace.json is an open standard for repository-scoped behavioral intelligence: a committed, evidence-tiered record of which files break and which change together, readable by any agent and enforceable before an edit lands.

One spec, multiple consumers: Codex and Buildomator (formerly gsd-plugin) both read workspace.json to give agent platforms codebase context.

Read the spec Comment on the RFC View examples
Spec version
v0.4 · unstable
File path
.agents/workspace.json
Reference impl
agents-audit@0.4.4
Consumer
Buildomator for Claude Code
License
Apache 2.0

01 · The Problem

Your agents read the code.
They don't know what it means.

Every codebase has files that everyone is afraid of. The authentication flow that broke twice last year. The webhook handler nobody fully understands. The component that was AI-generated, then patched fourteen times. This information lives in the heads of senior engineers and in Slack threads from six months ago. It does not live anywhere a coding agent can find it.

When an agent picks up a task, it sees a flat repository. It cannot tell that one file has been the source of half your production incidents this quarter, or that changing one type definition cascades into seven others. So it works confidently — and it breaks things confidently.

AGENTS.md helps. It gives agents a place to read instructions. But instructions are prose, written by humans, and they age. A codebase changes; the file describing it in words cannot keep up. There is no mechanism to tell an agent what is true about the repository right now — only what a developer wrote about it at some point in the past.

02 · The Solution

A machine-generated layer
of codebase truth.

workspace.json is placed at .agents/workspace.json and committed to version control. Tooling generates it — from git history, IDE telemetry, CI signals, and behavioral observation. Agents read it before they act. Developers commit it alongside the code it describes.

File Role Author Updates
AGENTS.md Prescriptive — what agents should do Human By hand
workspace.json Descriptive — what is currently true Tooling Automated

The two files are designed to compose. A repo can have both, either, or neither. Tools that consume AGENTS.md continue to work unchanged. Tools that also consume workspace.json get richer, current context.

03 · Signal Families

Four things your agents should know
before they edit anything.

.agents/workspace.json
{
  "manual": {},
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-07-30T12:47:49.867Z",
    "by": { "name": "agents-audit", "version": "0.4.4" },
    "frameworkManifest": [],
    "fileIndex": {},
    "topology": {
      "packageCount": 0,
      "type": "single-package",
      "ciProvider": "github-actions",
      "agentFiles": {
        "agentsMd": "AGENTS.md",
        "workspaceJson": ".agents/workspace.json"
      }
    },
    "hygiene": {
      "score": 100,
      "grade": "A",
      "failCount": 0,
      "warnCount": 0,
      "scannedAt": "2026-07-30T12:47:49.867Z"
    }
  },
  "agents": {},
  "health": {
    "intelligenceState": "INSUFFICIENT_DATA",
    "observationCount": 0,
    "confidence": 0
  }
}

This is the real, current output of npx agents-audit@0.4.4, run against this repository — reproduce it yourself rather than trust this page.

Producer identity

The artifact records the generator, its version, and generation time. It does not infer evidence that the producer did not emit.

Discovery

The producer describes the repository topology and canonical .agents/workspace.json location used by consumers.

Hygiene

agents-audit's original function — an AGENTS.md audit score — ships alongside the newer behavioral fields, not replaced by them.

Known limits

specVersion reads 0.3 here. The v0.4 schema defines coChange, fragility, and conventions, but the reference generator does not emit them yet — that gap is the spec's, not this page's, and it's stated here rather than hidden behind a nicer example.

04 · How It Works

Three steps. No lock-in.

  1. Generate

    Run npx agents-audit scan . in any repository. The reference CLI emits a conformant workspace.json under .agents/. For richer signals — fragility derived from incident history, behavioral co-change — pair with a daemon that observes sessions over time.

  2. Commit

    Add .agents/workspace.json to version control. Every contributor, every CI run, and every agent session now shares the same view of the repository's current state.

  3. Consume

    Any AI coding agent that reads workspace.json gets structured, current context before it acts. No configuration required beyond knowing where to look.

05 · For Implementers

Build a generator. Build a consumer.
Validate against the schema.

The spec is at workspacejson.dev/spec. The JSON Schema is served at workspacejson.dev/schema/v1.json and can validate any generated file in CI. The npm packages @workspacejson/spec and @workspacejson/rules expose the schema and validation rules for TypeScript integrations.

If you're building a generator or consumer, open an issue in the workspacejson/cli tracker. Canonical source and compatibility material are maintained in public.

Showcase

A silent zero, found and fixed.

DataHub knows lineage and schema. Git knows which files change together. The join sounds trivial: a dbt model is a file. But when a dbt project lives in a subdirectory, every lookup misses and the join returns zero rows, silently, with no error. Tally is a Change Impact Cockpit that resolves the mismatch, joins catalog context with repository evidence, and attaches a bounded receipt to every claim.

Read the Tally showcase for the five-act narrative: the silent failure, the mechanism, the evidence that changed the plan, the verifiable receipt, and the honest evidence boundary.

Read the showcase Inspect the evidence

From the blog

All posts →

The spec is a starting point,
not a finished standard.

v0.4 is a draft. The signal families are defined; the computation methods are intentionally open. What confidence scores should look like, how multiple generators should merge overlapping outputs, what negative space means for files the generator inspected and had nothing to say about — these are open questions with no settled answers yet.

Comment. Argue. Implement a draft.

The spec exists to be torn apart in public.

Read the spec Comment on the RFC