I'm the author of workspace.json, an open spec for machine-generated codebase intelligence. I'm filing this issue because the AAIF Technical Committee, in declining workspace.json for foundation intake (aaif/project-proposals#27), explicitly assigned this coordination as the first prerequisite for a future resubmission: workspace.json should not propose itself as a sibling to AGENTS.md without the AGENTS.md community having been in the conversation about how those files relate. This is that conversation.
The gap this addresses
Reading through the 73 open issues here, one thing is absent from every proposal: a principled treatment of machine-generated context. Issues #106, #71, #3, and #166 all gesture at structured or writable agent context, but every proposal assumes a human author. No existing proposal addresses what happens when CI tooling, a behavioral daemon, or the agents themselves write structured codebase state into the repo.
workspace.json is specifically that artifact.
What workspace.json is (and isn't)
workspace.json is a JSON file placed at .agents/agents.workspace.json (v0.3 schema) and committed to version control. It is descriptive — it records what is currently true about a codebase, generated by tooling, not written by humans:
- Fragility scores per file (derived from revert/fixup density in git history)
- AI attribution signals (which files have high AI-generated change ratios)
- Co-change clusters (files that move together under behavioral observation)
- Session learnings (patterns surfaced across AI coding sessions)
- Health metadata (schema version, generation timestamp, staleness signal)
What it explicitly is not: instructions, rules, permissions, or behavioral directives. Those belong in AGENTS.md.
The relationship as we've defined it:
| File |
Role |
Author |
Updates |
AGENTS.md |
Prescriptive — what agents should do |
Human |
Human commits |
agents.workspace.json |
Descriptive — what is currently true |
Tooling / CI |
Automated |
They compose naturally: an agent reads AGENTS.md to understand how to behave, then reads agents.workspace.json to understand what the codebase actually looks like right now. Neither file duplicates the other's role.
Current adoption
jnuyens/gsd-plugin v2.42.3 (released May 10) is the first independent consumer — a Claude Code plugin by Jasper Nuyens, unaffiliated with Vreko, that reads workspace.json to surface codebase intelligence directly in Claude Code sessions.
The specific ask
A mutually-acknowledged scope statement — a short, agreed-upon description of how AGENTS.md and workspace.json are orthogonal and composable — that can be referenced in both projects' documentation. I'm not asking for normative changes to AGENTS.md, for workspace.json to be referenced prescriptively, or for any merge of the two concepts.
The form is up to this community: a paragraph in the README, a comment from maintainers acknowledging the distinction, a link in the related projects section of agents.md. I'll work with whatever fits here. If it's useful, I'm happy to draft a PR against the README with proposed language for maintainers to accept, reject, or modify.
Why this matters for AGENTS.md specifically
The open issues touching machine-generated data (#3, #71, #106, #166) currently have no resolution path because the format has no answer for "what if the agent didn't write this, tooling did?" A clear scope boundary gives AGENTS.md a principled answer: AGENTS.md is the human-authored prescriptive layer; machine-generated descriptive state has its own artifact. That separation keeps AGENTS.md's simplicity intact while allowing the ecosystem to grow.
Links
I'm the author of workspace.json, an open spec for machine-generated codebase intelligence. I'm filing this issue because the AAIF Technical Committee, in declining workspace.json for foundation intake (aaif/project-proposals#27), explicitly assigned this coordination as the first prerequisite for a future resubmission: workspace.json should not propose itself as a sibling to AGENTS.md without the AGENTS.md community having been in the conversation about how those files relate. This is that conversation.
The gap this addresses
Reading through the 73 open issues here, one thing is absent from every proposal: a principled treatment of machine-generated context. Issues #106, #71, #3, and #166 all gesture at structured or writable agent context, but every proposal assumes a human author. No existing proposal addresses what happens when CI tooling, a behavioral daemon, or the agents themselves write structured codebase state into the repo.
workspace.json is specifically that artifact.
What workspace.json is (and isn't)
workspace.json is a JSON file placed at
.agents/agents.workspace.json(v0.3 schema) and committed to version control. It is descriptive — it records what is currently true about a codebase, generated by tooling, not written by humans:What it explicitly is not: instructions, rules, permissions, or behavioral directives. Those belong in AGENTS.md.
The relationship as we've defined it:
AGENTS.mdagents.workspace.jsonThey compose naturally: an agent reads AGENTS.md to understand how to behave, then reads
agents.workspace.jsonto understand what the codebase actually looks like right now. Neither file duplicates the other's role.Current adoption
jnuyens/gsd-plugin v2.42.3 (released May 10) is the first independent consumer — a Claude Code plugin by Jasper Nuyens, unaffiliated with Vreko, that reads workspace.json to surface codebase intelligence directly in Claude Code sessions.
The specific ask
A mutually-acknowledged scope statement — a short, agreed-upon description of how AGENTS.md and workspace.json are orthogonal and composable — that can be referenced in both projects' documentation. I'm not asking for normative changes to AGENTS.md, for workspace.json to be referenced prescriptively, or for any merge of the two concepts.
The form is up to this community: a paragraph in the README, a comment from maintainers acknowledging the distinction, a link in the related projects section of agents.md. I'll work with whatever fits here. If it's useful, I'm happy to draft a PR against the README with proposed language for maintainers to accept, reject, or modify.
Why this matters for AGENTS.md specifically
The open issues touching machine-generated data (#3, #71, #106, #166) currently have no resolution path because the format has no answer for "what if the agent didn't write this, tooling did?" A clear scope boundary gives AGENTS.md a principled answer: AGENTS.md is the human-authored prescriptive layer; machine-generated descriptive state has its own artifact. That separation keeps AGENTS.md's simplicity intact while allowing the ecosystem to grow.
Links