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.

[clay-good]

openspec/config.yaml is the equivalent, and you were right in your follow-up.

Two fields, documented in Customization:

• context: — injected into every planning request. Architecture guidelines, conventions, tech stack, anything the agent should always know.
• rules: — per-artifact, injected only for the matching artifact (e.g. spec rules that don't clutter the proposal).

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
rules:
  specs:
    - Use Given/When/Then format

On referencing external .md files: not supported — context: is inline text with a 50 KB hard cap (MAX_CONTEXT_SIZE). The practical split that works: keep the long documents where they are, and use context: for the short, always-true rules plus pointers to those paths (Architecture: see docs/arch.md) so the agent opens them when relevant. That keeps you well under the cap and avoids paying for the full text on every request.

Closing as answered — reopen or comment if your case is different.