Different openspec/project.md to root/AGENTS.md

[DasBen]

Can someone explain to me why pretty much all of project.md could be done by the AGENTS.md?

Project Conventions, Domain Context, Important Contraints and Dependencies should matter for all Agents on the repository and can therefore be reused. I tried this and i do not see a difference. What am I missing?

[MessiasLima]

I'm also wanted to know the difference between these two files. They look to serve the same purpose

[benoitheinrich]

Could it be to make openspec specific files AGENTS.md files upgradable by openspec (when installing a new version of openspec) without taking the risk of affecting the generated project.md file ?

I suppose AGENTS.md, like the various rules / workflows / commands that come from openspec could change overtime with new versions of openspec, so they are part of the openspec domain and apply to any project, while project.md and openspec/changes are related to your project only and so will differ from one project to the other.

By keeping a nice separation between the two it allows safer openspec updates without taking the risk of affecting your own project files.

I think we can think of this as a separation of concern principle.

[DasBen]

Could it be to make openspec specific files AGENTS.md files upgradable by openspec (when installing a new version of openspec) without taking the risk of affecting the generated project.md file ?

I suppose AGENTS.md, like the various rules / workflows / commands that come from openspec could change overtime with new versions of openspec, so they are part of the openspec domain and apply to any project, while project.md and openspec/changes are related to your project only and so will differ from one project to the other.

By keeping a nice separation between the two it allows safer openspec updates without taking the risk of affecting your own project files.

I think we can think of this as a separation of concern principle.

If that would be the reason, then it would make no sense to have this Block auto prefixed on existing root/AGENTS.md files:

<!-- OPENSPEC:START -->
# OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open `@/openspec/AGENTS.md` when the request:
- Mentions planning or proposals (words like proposal, spec, change, plan)
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- Sounds ambiguous and you need the authoritative spec before coding

Use `@/openspec/AGENTS.md` to learn:
- How to create and apply change proposals
- Spec format and conventions
- Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

<!-- OPENSPEC:END -->

I have experimented on this for weeks now. At least for me it works, when:

• openspec/AGENTS.md only containts the Openspec Flow
• root/AGENTS.md containts all Agent relevant information, coding principles and rules
• openspec/project.md is pretty useless and only contains for me te sections "Purpose" and "Tech Stack". Everything else has been removed.

This works on private as well as corporate projects for me.