Scope relationship between AGENTS.md and workspace.json — request for a joint statement

Aperta
  • Qualcosa non va?
#186 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
json, markdown
Ambito
documentation

Direzione di ricerca

Read the AGENTS.md README and its related-projects section, then the linked issues #3, #71, #106, #166 and the AAIF proposal #27 to see the unresolved machine-generated context gap. The ask is a short, mutually acknowledged scope statement distinguishing human-authored AGENTS.md from tooling-written .agents/agents.workspace.json. Done means maintainers and the workspace.json author agree on wording and it is linked from both projects' docs; no normative change to AGENTS.md is proposed.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
TypeScript
Stelle
24.8k
Fork
1.9k
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di agentsmd/agents.md

Tutte le issue di agentsmd/agents.md

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.