Ecosystem — AGENTS.md, MCP, Claude Code, Cursor, Goose & More

workspace.json is one piece of a larger set of open conventions and tools for AI-native development. This page describes how it fits alongside AGENTS.md, the Model Context Protocol, and the major AI coding agent tools.

workspace.json and AGENTS.md

AGENTS.md is a community convention for prose instructions to AI coding agents. Originating with Codex and now used by Cursor, Claude Code, Goose, and others, it answers the question: what should the agent do?

workspace.json answers a different question: what is true about the codebase? The two files address complementary layers:

File	Layer	Authored by	Question answered
AGENTS.md	Prescriptive	Humans	What should agents do?
workspace.json	Descriptive	Tooling	What is true about the code?

Neither replaces the other. A repository with both gives agents the fullest context: prose instructions about process and intent alongside machine-derived intelligence about structure, fragility, and history.

The agents section of workspace.json explicitly references AGENTS.md and other agent instruction files so that consumers can discover the full set of context available in a repository.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and MCP

The Model Context Protocol (MCP) is an open protocol by Anthropic for connecting AI models to external context sources — file systems, databases, APIs, and tools. MCP servers expose resources and tools that AI clients can invoke at runtime.

workspace.json and MCP operate at different points in the agent lifecycle:

• workspace.json is a static artifact committed to version control. It provides baseline intelligence that is always available, requires no live process, and works in any context (local IDE, CI, code review, remote agent).
• MCP enables live, dynamic context — querying a running service for current state, invoking tools, or accessing resources that change faster than a committed file can track.

The two are complementary. An MCP server can read workspace.json to seed its context (Vreko does this in its MCP server). An agent receiving MCP context can use workspace.json for the structural and historical signals that MCP doesn’t model natively.

An MCP server that reads and exposes workspace.json is a reference integration pattern — see the Implementations page for tools that implement this.

workspace.json does not depend on MCP and works without it. workspace.json is proposed for donation to AAIF — view the proposal.

AI Coding Agent Integrations

workspace.json and Claude Code

Claude Code reads AGENTS.md for prose instructions. workspace.json is the structured complement: machine-generated codebase facts that keep agents grounded in what is actually true about the repository.

The two-file model:

File	What it provides
AGENTS.md	How to contribute, what agents should and shouldn’t do
agents.workspace.json	Fragility scores, framework map, hot files, co-change patterns

When Claude Code has access to both, it can make better-informed decisions about which files to modify, which areas carry risk, and what the codebase architecture looks like — without reading every file.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and Cursor

Cursor uses .cursor/rules and AGENTS.md for agent instructions. workspace.json sits alongside these as the structured intelligence layer.

Cursor agents can consume agents.workspace.json to understand codebase fragility, framework dependencies, and file importance without reading the entire codebase. The workspace.json spec is tool-agnostic — any agent that can read a JSON file from .agents/agents.workspace.json can benefit from it.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and Goose

Goose is Block’s open-source AI developer agent. Goose reads AGENTS.md when present and is a primary consumer of the agent instruction convention that workspace.json is designed to complement.

Goose’s toolbox model (extensions that provide context and actions) maps naturally onto workspace.json: an extension could read workspace.json to surface fragility warnings, surface co-change patterns before edits, or report workspace health state. This integration is not built yet and is listed in the Implementations page as an opportunity.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and Cline

Cline uses .clinerules for agent instructions. workspace.json provides the structured descriptive layer alongside .clinerules — codebase facts that Cline agents can use to make better editing decisions.

The agents section of workspace.json explicitly references .clinerules so that consumers can discover the full set of instruction files in the repository alongside the structured intelligence.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and Windsurf

Windsurf (by Codeium) supports agent context through rule files. workspace.json provides the structured intelligence layer alongside Windsurf’s instruction files — fragility scores, framework dependencies, and file modification patterns that improve agent decision quality.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and GitHub Copilot

GitHub Copilot’s workspace and agent features can benefit from the structured context in workspace.json. The generated section — fragility scores, co-change patterns, framework manifest — provides the kind of repository intelligence that helps Copilot agents reason about impact and risk.

workspace.json is proposed for donation to AAIF — view the proposal.

workspace.json and Goose (Extended)

Goose is Block’s open-source AI developer agent. Goose reads AGENTS.md when present and is a primary consumer of the agent instruction convention that workspace.json is designed to complement.

Goose’s toolbox model (extensions that provide context and actions) maps naturally onto workspace.json: an extension could read workspace.json to surface fragility warnings before edits, expose co-change patterns as Goose context, or report workspace health state. This integration is listed in the Implementations page as an opportunity for tool authors.

The Broader Picture

workspace.json is proposed for contribution to the Agentic AI Foundation (AAIF), the emerging open-governance body for agentic AI standards. The AAIF’s mandate includes specifications that cross tool boundaries — standards that Cursor, Cline, Continue, Goose, Claude Code, and others can all implement without one vendor’s governance.

The spec is designed for this role:

• Vendor-neutral: no dependency on any particular AI provider or tool
• Minimal: a small surface area that’s easy to implement correctly
• Composable: works alongside rather than replacing existing conventions
• Open: Apache 2.0 license, public RFC process, community governance

The goal is a stable, widely-adopted standard for structured codebase intelligence — so that any agent, in any tool, working in any repository can access the same quality of context that today requires proprietary integrations.

See Governance for the current status of the AAIF donation proposal.