Exploration: giving project knowledge beyond behavior a home in OpenSpec

What we're exploring

Behavior specs ("when X, the app does Y") are OpenSpec's lasting, structured home for project knowledge. As projects grow, teams also record other things: performance budgets, decisions, a glossary, shared rules. We want to explore how OpenSpec could support that knowledge as well as it supports behavior.

Where this came from

While building a desktop app with OpenSpec, we wanted to record performance budgets, like "startup stays under 300 ms on this machine". That's a number, measured over many runs on a named machine, not a when/then. The options we have today each fit it partly:

• A spec is built for when/then scenarios, so the machine, the runs and the threshold don't have a natural place.
• design.md is archived with its change.
• Config context is free text, sent every time.

We kept it in a docs folder for now, next to the project's glossary and decisions.

Related threads

The same question has come up in different forms:

• ADRs (#557 → D1553)
• a lasting architecture doc (D592)
• shared rules (#447)
• implementation and test details (#1967)
• what belongs in context (#1966)

Looking at these together may show one shared need rather than five separate ones.

What makes it worth exploring carefully

• It builds on earlier work. Collections explored a similar idea, and we simplified them away in June 2026 in favor of "specs are what is true, work is what is in motion". Any direction should fit that rule, or show why it should change.
• Needs differ by project and grow over time. Many projects only need specs. Others need more, and not from day one.
• Some knowledge spans repos. An end-to-end budget can cross a front end, a back end and a queue.
• It should stay easy. Stating a fact should be enough; nobody should have to learn where things go.
• Existing projects must keep working. The spec format, validation and archive (#666, #1706) and current openspec/specs/ folders stay stable.

Next steps

1. Research: what teams keep next to their specs today, how other teams and tools approach it, and what we learned from collections. OpenAI's harness engineering (Feb 2026) builds this by hand for one repo: separate docs for reliability, security and quality next to product specs, performance budgets written as plain constraints, and linters plus a doc-gardening agent to keep them current. Worth studying what a product version of that would need beyond one repo.
2. Prototype: run the desktop app's budgets end to end with the smallest workable change. Separately, test whether an agent can reliably tell a behavior from a budget from a decision.
3. Then choose a shape. That could be a small addition or a change to the product experience; the research decides.