Historical namespace

Canonical development of the workspace.json producer has moved to workspacejson/cli, published as @workspacejson/cli with the same command surface. The specification itself lives in workspacejson/standard.

This repository is retained because agents-audit on npm is still published from here. It is publication provenance, not current authority. New work belongs in the workspacejson organization.

workspace.json is an open specification for structured AI agent codebase intelligence. A machine-generated JSON file at .agents/workspace.json gives AI coding agents structured context about your repository.

(spec · rendered docs · changelog)

Shipped consumer integrations:

• Buildomator (formerly gsd-plugin) — independent Claude Code implementation reading .agents/workspace.json at SessionStart
• @workspacejson/codex-mcp — Codex MCP server for consulting repository intelligence before edits

workspace.json separates machine-generated topology from human-authored manual evidence. Regeneration updates the generated topology while preserving manual evidence verbatim. See Billfold for a production workflow built around this distinction.

This repository is the publication source for the agents-audit release family. It is not the canonical source for the specification or the producer — see the notice at the top.

Packages

Package	Purpose
@workspacejson/spec	JSON Schema and TypeScript types for workspace.json
@workspacejson/rules	Deterministic parser, scanner, validator, and rule engine
agents-audit	CLI for scanning AGENTS.md hygiene and workspace metadata

Spec Source

The canonical specification lives at packages/spec/.

• JSON Schema: packages/spec/schema/v1.json
• TypeScript types: packages/spec/src/types.ts
• Rendered: workspacejson.dev/spec/

Quick Start

# Audit AGENTS.md hygiene in any repo
npx agents-audit

# Generate .agents/workspace.json
npx agents-audit generate

Repository Layout

agents-audit/
├── packages/
│   ├── spec/          — JSON Schema + TypeScript types
│   ├── rules/         — Rule engine and validator
│   └── agents-audit/  — CLI binary
├── .github/
├── pnpm-workspace.yaml
├── package.json
├── README.md
└── CHANGELOG.md

Local Development

pnpm install
pnpm -r typecheck
pnpm -r test
pnpm -r build

To run the CLI against the current repository:

pnpm --filter agents-audit build
node packages/agents-audit/dist/cli.js scan .

Release Notes

Version history is tracked in CHANGELOG.md. GitHub release tags mirror npm package versions.

Support Files

• CONTRIBUTING.md
• SECURITY.md
• AGENTS.md