Descriptive codebase intelligence for AI-native development.
workspace.json is an Apache-2.0 open standard for committed repository intelligence. Its canonical artifact is the daemon-free .agents/workspace.json file: readable, reviewable, and useful without requiring a service to be running.
Documentation · Specification · Generate an artifact · Use it in tools
Generate the committed artifact:
npx @workspacejson/cli generate .Validate it against the released specification:
npx workspacejson-spec validate .agents/workspace.jsonThe standard describes a codebase. It does not prescribe approval gates, enforcement policy, or how a team must work.
| Repository | Owns |
|---|---|
workspacejson/standard |
Specification, JSON Schema, validation semantics, deterministic rules, compatibility profiles, conformance fixtures, ADRs, and governance |
workspacejson/cli |
Neutral producer, repository scanning, deterministic generation and reconciliation, and CLI distribution |
workspacejson/integrations |
MCP, Codex, VS Code, CI, skills, plugins, and other host-specific consumers and adapters |
workspacejson/workspacejson.dev |
Assembled documentation and the public publishing surface at workspacejson.dev |
The dependency direction is intentionally one-way:
standard
↓
cli integrations
\ /
workspacejson.dev
standard depends on none of the other repositories. cli and integrations consume released standard contracts. The documentation site materializes pinned sources rather than becoming a second editable source of truth.
Four externally consumed paths form the current compatibility floor:
manual.fragileFiles
manual.coChangePatterns
generated.fileIndex
generated.frameworkManifest
Changes to those paths are treated as breaking changes regardless of package-semver optics.
workspacejson/datahub-agent contains Tally — Change Impact Cockpit, a reference application built with workspace.json and DataHub.
Tally demonstrates how catalog identity can be resolved to exact repository code and carried into a bounded evidence receipt. It is not part of the workspace.json specification.
- The committed artifact must remain useful without a daemon.
- The standard is descriptive, never prescriptive.
- Public specification work has no dependency on private Vreko or
@marcelle-labs/*source. - Published package state is established by the npm registry, not by repository prose.
- Missing evidence is reported as missing evidence, never as safety.
The project is currently maintained under a single-steward model while governance, release authority, external-consumer participation, and donation readiness are made reproducible. No standards-body stewardship transfer has occurred.
See:
Apache-2.0. Copyright the workspacejson contributors.