Migrating Project Knowledge from Amazon Q Rules to OpenSpec

[berdugoyohan]

Migrating Project Knowledge from Amazon Q Rules to OpenSpec

I'm in the process of migrating from Amazon Q to OpenSpec and looking for guidance on where to place project-level knowledge.

In Amazon Q, I relied on Rules to store a variety of project context, including:

• Architecture guidelines
• Code styling conventions
• External dependency documentation
• Other project-specific knowledge

All of this information is currently maintained in Markdown (.md) files.

What is the recommended location or mechanism in OpenSpec for storing this type of project knowledge? Is there an equivalent to Amazon Q's Rules, or a best practice for organizing these files within an OpenSpec project?

Any pointers to relevant documentation would be appreciated. Thanks!

[berdugoyohan]

If I understand correctly, this should go in the config.yaml file. But I couldn't find clear guidance in the repo docs to confirm that.

My concern is that based on the docs, config.yaml context gets actively injected into every OpenSpec planning request, and project context is capped at 50KB so I want to make sure this is the right place for it.

Also - does it is possible to reference external md files from config.yaml? For example:

• Architecture docs: x/y/z/arch.md
• Best practices: x/y/z/best-practices.md

Would love to get a definitive answer from one of the contributors or someone who's actually done this in practice.