workspace.json - How Vreko Structures Codebase Intelligence

workspace.json is an open standard for machine-readable codebase intelligence. It defines a structured format for the metadata that AI agents need to understand a codebase before writing code - fragility scores, framework manifests, co-change patterns, and AI contribution history.

Vreko implements this standard as the delivery format for everything it learns about your project.

What Vreko Populates

The Vreko service writes agents.workspace.json to your project root after each session. The fields Vreko populates:

Field	Type	What It Captures
fragility	Record<string, number>	Per-file risk score (0–100). High scores predict breakage under AI edits.
fileIndex	FileIndex[]	Annotated file list with AI modification counts and last-touched timestamps.
frameworkManifest	FrameworkManifest	Detected frameworks, runtimes, and package managers in the workspace.
aiModificationCount	number	Total AI-attributed changes across the project lifetime.
coChangePatterns	CoChangePattern[]	File pairs that historically change together - agents use this to avoid partial edits.

What it looks like after vr init

Right after vr init, before Vreko has observed any sessions, the file is mostly empty - the service is in its initial observing state and confidence is 0.0. It fills in as Vreko watches your work:

{
  "manual": { "fragileFiles": [], "coChangePatterns": [] },
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-29T18:20:00.000Z",
    "by": "vreko-daemon",
    "fileIndex": {
      "src/auth/session.ts": { "changeCount": 0, "revertCount": 0 }
    },
    "frameworkManifest": [],
    "coChange": [],
    "fragility": []
  },
  "agents": { "context": "Workspace initialized. Vreko is observing; intelligence will populate over the next few sessions." },
  "health": {
    "intelligenceState": "OBSERVING",
    "observationCount": 0,
    "confidence": 0.0,
    "averageFragility": 0.0,
    "fragileFileCount": 0
  }
}

As Vreko observes sessions, fragility, coChange, and fileIndex fill in, observationCount climbs, and confidence rises toward a steady state.

How the Service Writes the File

On every Vreko session, the Vreko service recalculates intelligence state and writes a fresh agents.workspace.json. The cycle:

1. Observe - the service watches file saves and detects AI tool activity
2. Score - updates fragility scores and co-change patterns based on the session
3. Write - atomically writes agents.workspace.json with the current state

The write completes in under 200ms. Your agent sees the updated file on the next tool call.

How AI Agents Consume It

AI agents that support the workspace.json standard read agents.workspace.json at session start, before writing any code. This gives them:

• Which files to treat as fragile (high fragility score → be conservative)
• Which files tend to break together (co-change patterns → edit all of them or none)
• What frameworks are present (frameworkManifest → use correct APIs)
• How much of the codebase has AI-touched code (aiModificationCount → calibrate review depth)

Vreko also delivers this intelligence through rules files (.cursor/rules, CLAUDE.md) and MCP tools for agents that don’t yet read agents.workspace.json directly.

Full Specification

The complete field definitions, JSON schema, and versioning policy are maintained at workspacejson.dev/spec.

To validate your agents.workspace.json against the spec or compare it against other projects, use the agents-audit reference CLI.

Next Steps

• How It Works - how Vreko builds this intelligence over time
• CLI Reference - vr commands for generating and inspecting agents.workspace.json
• MCP Setup - MCP tools that expose workspace.json fields to your AI agent