Skip to content
workspace.json
Blog

workspace.json — open spec for codebase truth

OPEN SPECIFICATION · v0.3 · Apache 2.0

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

workspace.json is a single JSON file, committed to version control, that tells AI coding agents what they need to know before they touch your repository — what's fragile, what changes together, what AI wrote, and what's been quietly drifting.

Read the spec Comment on the RFC View examples
Spec version
v0.3 · draft
File path
.agents/agents.workspace.json
Reference impl
[email protected]
First consumer
gsd-plugin for Claude Code (v2.42.3, Jasper Nuyens)
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/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
agents.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/agents.workspace.json
{
  "$schema": "https://workspacejson.dev/schema/v1.json",
  "specVersion": "0.3",
  "manual": {
    "description": "TypeScript monorepo: web dashboard, API server, and shared packages.",
    "techStack": ["TypeScript", "Next.js 15", "Hono", "PostgreSQL", "Drizzle ORM"],
    "conventions": [
      "Named exports only — no default exports",
      "Throw typed errors; catch only at route boundary",
      "Database queries go through the repository layer"
    ],
    "fragileFiles": [
      {
        "path": "src/auth/session.ts",
        "reason": "Single point of failure for all authentication. Broke twice in Q1."
      }
    ],
    "coChangePatterns": [
      {
        "files": ["src/auth/session.ts", "src/auth/tokens.ts"],
        "note": "Token invalidation depends on session shape. Always change together."
      }
    ]
  },
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-12T08:30:00.000Z",
    "by": { "name": "agents-audit", "version": "0.3.0" },
    "fileIndex": {
      "src/auth/session.ts": {
        "fragility": 0.87,
        "aiModificationCount": 3,
        "humanModificationCount": 19
      },
      "src/webhooks/handler.ts": {
        "fragility": 0.71,
        "aiModificationCount": 2,
        "humanModificationCount": 28
      },
      "src/components/DataTable.tsx": {
        "fragility": 0.22,
        "aiModificationCount": 22,
        "humanModificationCount": 14
      }
    },
    "coChangeClusters": [
      {
        "files": ["src/auth/session.ts", "src/auth/tokens.ts"],
        "correlation": 0.94,
        "note": "Token invalidation depends on session shape."
      }
    ]
  },
  "agents": {
    "contextFiles": [
      { "path": "AGENTS.md", "role": "instructions" }
    ]
  },
  "health": {
    "confidence": 0.83,
    "generatorId": "agents-audit",
    "lastObservedAt": "2026-05-12T08:30:00.000Z"
  }
}

Fragility

Derived from incident history, revert density, and fix-on-fix patterns. A score of 0.87 on src/auth/session.ts means: this file breaks under change, and the record shows it. An agent that knows this slows down. One that doesn't makes confident changes.

Co-change

Files that move together under behavioral observation — not static imports, but actual coupling. If session.ts and tokens.ts co-change at 0.94 correlation, an edit to one without the other is a risk the spec can surface before it becomes an incident.

Attribution

What AI wrote versus what humans last touched. Not blame — posture. A file that is 61% AI-authored and has been patched fourteen times since generation is a different kind of fragile than one where every line was written deliberately.

Behavior

What the code is observed doing in production. This family is the most open in v0.3; the spec defines the shape, not the source. Generators may draw from APM data, test coverage signals, or deployment frequency.

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 agents.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/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 agents.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.

The first independent consumer is gsd-plugin for Claude Code (v2.42.3, Jasper Nuyens) — a Claude Code plugin that reads workspace.json to surface fragility and co-change signals directly in Claude Code sessions.

If you're building a generator or consumer, open an issue in the workspace-json/agents-audit tracker. The RFC process is open and the spec is designed to be argued with in public.

From the blog

All posts →

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

v0.3 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