workspace.json v0.3 Specification

Version: v0.3 · Status: Active · License: Apache 2.0 · Proposed: AAIF JSON Schema: www.workspacejson.dev/schema/v1.json · npm: @workspacejson/spec

Quick Reference

Field	Stability	Type	Description
`version`	stable	string	Spec version. Required.
`manual`	stable	object	Human-authored context
`generated`	stable	object	Machine-generated intelligence
`agents`	stable	object	Agent instruction file references
`health`	stable	object	Codebase health signals
`structuralPhase`	experimental	string	Subject to revision per section 4
`llmContextStaleness`	experimental	number	Subject to revision per section 4
`packageDensity`	experimental	number	Subject to revision per section 4
`testCoverageRatio`	experimental	number	Subject to revision per section 4
`bootstrapOverride`	experimental	object	Subject to revision per section 4

This document specifies workspace.json v0.3, a JSON file format for structured codebase intelligence consumed by AI coding agents. It is proposed as a complement to the AGENTS.md convention, which specifies prose instructions for agents. Where AGENTS.md addresses the prescriptive layer (what agents should do), workspace.json addresses the descriptive layer (what is true about the codebase).

This is a v0.3 specification. The core surface — file index, framework manifest, agent file references, and stable health signals — is intended to be stable. Fields explicitly marked [experimental] are subject to revision. See section 4 for the stability contract.

1. Introduction

1.1 Purpose

workspace.json provides AI coding agents with structured, machine-generated context about a codebase. Unlike AGENTS.md, which contains prose instructions authored by developers, workspace.json is generated by tooling that observes the codebase over time. It is committed to version control so that all consumers (developers, AI tools, CI systems) share a consistent view of the project.

The file is designed to be:

Machine-generated: Tooling regenerates it from observed codebase behavior, not from manual authoring. It does not go stale in the way prose does.
Committed to git: The entire team’s tooling shares one source of truth.
Incrementally adoptable: A minimal valid file (version field only) is useful. Richer fields add value as tooling matures.
Safe to commit: The schema explicitly excludes secrets, PII, and content that belongs in .gitignore.

1.2 Relationship to AGENTS.md

AGENTS.md and workspace.json address complementary concerns:

File	Layer	Authored by	Content type
AGENTS.md	Prescriptive	Humans	Prose instructions
workspace.json	Descriptive	Tooling	Structured intelligence

A repository MAY have both, either, or neither. Tools that consume AGENTS.md are unaffected by the presence or absence of workspace.json. Tools that consume both receive richer context.

1.3 Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

2. File Location and Discovery

2.1 Default Location

The canonical location for agents.workspace.json is:

.agents/agents.workspace.json

relative to the repository root. This places it alongside other agent context files in the .agents/ directory convention established by the AGENTS.md ecosystem.

2.2 Discovery Rules

Consumers MUST search for agents.workspace.json in the following order:

.agents/agents.workspace.json (canonical location)
agents.workspace.json at repository root (legacy fallback)

If neither location contains a valid agents.workspace.json file, the consumer SHOULD proceed without agents.workspace.json context. Consumers MUST NOT error on the absence of agents.workspace.json.

Generators SHOULD write to .agents/agents.workspace.json. Generators MAY also write to the repository root for backwards compatibility with consumers that predate this specification.

2.3 Multi-File Scenarios

In monorepo setups, each package MAY have its own agents.workspace.json describing the package’s local context. A root-level agents.workspace.json describes the repository as a whole. Consumers SHOULD prefer the nearest agents.workspace.json to the files being processed.

2.4 Version Compatibility

The generated.specVersion field governs compatibility between generators and consumers.

Consumers MUST check generated.specVersion to determine how to interpret the document. At v0.3, generated.specVersion is "0.3". Consumers that support v0.3 MUST reject documents where generated.specVersion is absent or does not equal "0.3" as structurally incompatible, and MUST surface a human-readable error. Consumers MAY support legacy v0.1/v0.2 documents by detecting the absence of generated.specVersion and falling back to the flat top-level shape.

agents.workspace.json specVersion "0.2" is not supported by this consumer (supports: "0.3").
Please regenerate your agents.workspace.json with a compatible tool.

3. Schema

workspace.json is a JSON object. The JSON Schema is available at www.workspacejson.dev/schema/v1.json.

3.1 Top-Level Structure `[stable]`

{
  "manual": {},
  "generated": {},
  "agents": {},
  "health": {}
}

All four top-level sections are REQUIRED in v0.3. Every valid v0.3 agents.workspace.json MUST include manual, generated, agents, and health. Sections MAY be empty objects. Consumers MUST NOT add extra top-level properties (additionalProperties: false).

Section roles:

Section	Authored by	Contains
`manual`	Developer	Human-authored project descriptions, conventions, fragility notes
`generated`	Tooling	Machine-derived file index, framework manifest, structural data
`agents`	Tooling	References to agent context files in the repository
`health`	Tooling	Workspace-level intelligence signals and confidence scores

3.2 The `manual` Section `[stable]`

The manual section contains developer-authored content. It is the workspace.json equivalent of a README for agent consumers.

{
  "manual": {
    "description": "TypeScript monorepo for the Acme platform: web, API, and shared packages.",
    "techStack": ["TypeScript", "Next.js 15", "PostgreSQL", "Drizzle ORM"],
    "conventions": [
      "All packages use named exports: no default exports",
      "Error handling: throw typed errors, catch at route/handler boundary only"
    ],
    "fragileFiles": [
      {
        "path": "packages/auth/src/index.ts",
        "reason": "Single point of failure for all authentication. High blast radius."
      }
    ],
    "coChangePatterns": [
      {
        "files": ["packages/contracts/src/user.ts", "apps/api/src/routes/users.ts"],
        "note": "Schema changes require simultaneous API route updates."
      }
    ]
  }
}

Fields:

description [stable]: Human-readable description of the repository. SHOULD be 1-3 sentences.
techStack [stable]: Array of technology names. SHOULD include major frameworks and runtimes.
conventions [stable]: Array of convention strings. Each entry SHOULD be a single actionable rule.
fragileFiles [stable]: Array of objects with path (relative) and reason (string). Files that require special care.
coChangePatterns [stable]: Array of objects with files (array of paths) and note (string). Files that must change together.

3.3 The `generated` Section `[stable]`

The generated section is written by tooling. Developers SHOULD NOT edit it manually.

{
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-12T12:00:00.000Z",
    "by": { "name": "vreko", "version": "0.3.0" },
    "fileIndex": {
      "src/index.ts": {
        "fragility": 0.12,
        "aiModificationCount": 4,
        "humanModificationCount": 12
      }
    },
    "frameworkManifest": [
      {
        "name": "Next.js",
        "version": "15.3.0",
        "confidence": 1.0
      }
    ]
  }
}

Fields:

specVersion [stable]: Schema version string. MUST be "0.3" for v0.3 compliant files.
generatedAt [stable]: ISO 8601 timestamp of generation time.
by [stable]: Object identifying the generator. Required fields: name (string), version (string).
fileIndex [stable]: Map of relative file paths to file-level intelligence objects. Keys MUST be relative paths with forward slashes.
frameworkManifest [stable]: Array of detected framework entries.

File index entry fields:

fragility [stable]: Float 0.0–1.0. Higher values indicate files that change more disruptively.
lastModified [stable]: ISO 8601 timestamp.
aiModificationCount [stable]: Count of AI-attributed modifications.
humanModificationCount [stable]: Count of human-attributed modifications.

3.4 The `agents` Section `[stable]`

Describes agent context files present in the repository.

{
  "agents": {
    "toolAgentFiles": [
      ".cursorrules",
      ".windsurfrules",
      "copilot-instructions.md"
    ],
    "referencedAgentFiles": [
      "AGENTS.md"
    ],
    "primaryAgentFile": "AGENTS.md"
  }
}

Fields:

toolAgentFiles [stable]: Tool-specific agent instruction files present in the repository.
referencedAgentFiles [stable]: Cross-tool agent files (AGENTS.md, CLAUDE.md, etc.).
primaryAgentFile [stable]: The single agent file recommended for general-purpose AI agent consumers. SHOULD be "AGENTS.md" when present.

3.5 Health Signals `[stable]`

The health section provides workspace-level intelligence state.

{
  "health": {
    "intelligenceState": "CONFIDENT",
    "observationCount": 1842,
    "averageFragility": 0.18,
    "fragileFileCount": 3,
    "confidence": 0.92
  }
}

Fields:

intelligenceState [stable]: One of "INSUFFICIENT_DATA", "OBSERVING", "CONFIDENT". Consumers SHOULD surface this to developers when not "CONFIDENT".
observationCount [stable]: Number of change events observed by the generator.
averageFragility [stable]: Float 0.0–1.0. Mean fragility score across all observed files.
fragileFileCount [stable]: Count of files with fragility ≥ 0.7.
confidence [stable]: Float 0.0–1.0. Generator confidence in the health signals.
bootstrapOverride [stable]: Float 0.0–1.0. When > 0, some scores are based on priors rather than observed data.

The precise computation methodology for fragility scores, confidence values, and related health signals is implementation-defined at v0.1. Consumers SHOULD treat these as opaque numeric signals within their documented ranges rather than assuming a specific algorithm. Future versions of this spec may standardize computation where interoperability requires it.

3.6 Experimental Fields

The following fields are part of the v0.3 schema but are marked [experimental]. They MAY change in minor versions without a major version bump.

health.structuralPhase [experimental]: Estimated structural lifecycle phase of the project.
health.llmContextStaleness [experimental]: Estimated fraction of context that has changed since last agent session.
generated.fileIndex[].packageDensity [experimental]: Density of dependency usage in a file.
generated.fileIndex[].testCoverageRatio [experimental]: Estimated test coverage ratio for a file.

4. Stability Annotations

4.1 Field-Level Stability

Fields in this specification carry one of three stability markers:

[stable]: Intended to remain compatible across all v0.x releases and v1.0. Generators and consumers MAY rely on these fields.
[experimental]: May change without a major version bump. Consumers SHOULD check the schema package changelog before relying on experimental fields.
[deprecated]: Slated for removal. Will carry a removal target version. No fields are deprecated in v0.1.

4.2 Version Contract

The generated.specVersion field identifies the schema version. See section 2.4 for the normative compatibility rules governing how consumers MUST handle version mismatches. In summary: documents where specVersion does not match the consumer’s supported version MUST be refused with a human-readable error; unknown fields within a supported version MUST be ignored.

Version bump policy:

Change type	Version impact
Add stable field	Minor bump (0.x → 0.x+1)
Remove stable field	Major bump (0.x → 1.0)
Change stable field semantics	Major bump
Add experimental field	Minor bump
Change experimental field	Minor bump

4.3 Breaking Changes Policy

Fields marked [stable] in v0.3 will not be removed or have their semantics changed in any v0.x release. Breaking changes to stable fields require a 1.0 version. This policy applies from the date of the v0.3 public release.

5. Security and Privacy

5.1 What MUST NOT Be Committed

workspace.json MUST NOT contain any of the following:

Generators MUST enforce these exclusions. If a generator cannot guarantee exclusion of a category, it MUST omit that field entirely.

5.2 Recommended Exclusions

Add .gitignore patterns to prevent accidental exposure if workspace.json were to contain sensitive data:

# agents.workspace.json is intended to be committed, but if your generator
# might include sensitive data, exclude it:

The default recommendation is to commit agents.workspace.json. If your organization has policies preventing structured metadata from being committed, exclude it and treat it as a local-only artifact.

workspace.json SHOULD NOT contain data that identifies individual contributors by name, email, or other personal identifiers. Fields like aiModificationCount and humanModificationCount are aggregate counts without attribution.

If a generator includes per-contributor data (e.g., commit author statistics), that data MUST be excluded before committing workspace.json.

6. Examples

6.1 Minimal Valid File

{
  "manual": {},
  "generated": {
    "specVersion": "0.3",
    "generatedAt": "2026-05-12T00:00:00.000Z",
    "by": { "name": "your-tool", "version": "1.0.0" }
  },
  "agents": {},
  "health": {}
}

All four top-level sections are required. manual, agents, and health may be empty objects. Within generated, only specVersion, generatedAt, and by are required; frameworkManifest and fileIndex are optional.

6.2 TypeScript Monorepo

See the Examples page for a full TypeScript monorepo workspace.json.

6.3 Python Single-Package

See the Examples page for a Python single-package workspace.json.

6.4 Polyglot Repository

See the Examples page for a polyglot repository workspace.json.

7. Prior Art and Acknowledgments

workspace.json draws conceptual inspiration from:

AGENTS.md: the community convention for prose agent instructions that this spec is designed to complement. workspace.json adopts the .agents/ directory convention and is explicitly designed not to replace AGENTS.md.
package.json: the model for a machine-readable project descriptor committed to version control.
devcontainer.json: the precedent for structured development environment metadata committed alongside code.
pyrightconfig.json / tsconfig.json: the model for tool-specific configuration files that tooling reads and humans occasionally edit.

8. License

workspace.json specification and all reference implementations are licensed under the Apache License 2.0.

The specification is proposed for donation to the Agentic AI Foundation (AAIF) upon reaching appropriate adoption milestones. See Governance for details.

9. Contributing

The specification is developed in public at github.com/workspace-json/agents-audit/tree/main/packages/spec.

Substantive changes go through a public RFC process documented in the repository’s CONTRIBUTING.md. The JSON Schema is available at https://www.workspacejson.dev/schema/v1.json and is updated with each spec release.

We are looking for contribution from AI coding tool teams (Cursor, Cline, Continue, Aider, Copilot, Zed, etc.) who would consume workspace.json in their tooling, and from tool authors who would generate workspace.json from behavioral observation.

workspace.json v0.3 Specification

Quick Reference

1. Introduction

1.1 Purpose

1.2 Relationship to AGENTS.md

1.3 Conventions

2. File Location and Discovery

2.1 Default Location

2.2 Discovery Rules

2.3 Multi-File Scenarios

2.4 Version Compatibility

3. Schema

3.1 Top-Level Structure [stable]

3.2 The manual Section [stable]

3.3 The generated Section [stable]

3.4 The agents Section [stable]

3.5 Health Signals [stable]

3.6 Experimental Fields

4. Stability Annotations

4.1 Field-Level Stability

4.2 Version Contract

4.3 Breaking Changes Policy

5. Security and Privacy

5.1 What MUST NOT Be Committed

5.2 Recommended Exclusions

5.3 GDPR Considerations

6. Examples

6.1 Minimal Valid File

6.2 TypeScript Monorepo

6.3 Python Single-Package

6.4 Polyglot Repository

7. Prior Art and Acknowledgments

8. License

9. Contributing

3.1 Top-Level Structure `[stable]`

3.2 The `manual` Section `[stable]`

3.3 The `generated` Section `[stable]`

3.4 The `agents` Section `[stable]`

3.5 Health Signals `[stable]`