Enhancement: Rules

[som45oul]

CHANGE TYPE

Minor, non breaking change

PROBLEM

Currently, there is no documented standard for adding conventions, standards and decisions to your project, meaning:

• Rules and conventions are tightly bound to project.md
• Sharing rules and standards or conventions between projects is difficult
• Community users have no way to share rules for common platforms, patterns, or design approaches
• Users are forced to repeatedly respecify standards to their tastes

PROPOSAL

Standardise on having a rules/ folder in the openspec folder

Within this folder are rules files, for example:

typescript.rules.md
python.rules.md
solid.rules.md
performance.rules.md
docs.rules.md

etc.

Each .rules.md file contains constraints and standards for the agent to follow relative to that domain (tech stack, business process, architecture, etc). Creating .rules.md files for specific domains is encouraged to foster portability and sharing between projects and users. Conceptually, this is a technology-agnostic approach similar to the one used by Cursor Directory.

These files can be organised as the project sees fit, and are referenced as necessary in project.md.

The baseline of this proposal is minimal: just add an openspec/rules folder during init, perhaps with an openspec.rules.md by default. The openspec.rules.md file would specify how rules should be created and managed by the agent, enabling customisability and consistency.

While the folder would be created by default, users are not compelled to use it. Its use is entirely optional.

A useful optional addition might be enabling a slash command to add new rules:

/openspec:rules Always use UPPER_CASE for constant names in python

The AGENT would need instructions on how to file such rules into useful .rules.md file groupings based on topic.

Alternatively, users could prefix their rule with the domain:
/openspec:rules python Always use UPPER_CASE for constants

The agent could then create or update python.rules.md

An alternative approach to pre-creating the rules folder could then be to create it on demand.

Rules could also be used as a pseudo memory bank for the agent, which could be useful as projects iterate and evolve.

BENEFITS

• Consistency: Standardises the approach across projects and organisations
• Visibility: Promotes a modular approach to composing SDD solutions
• Composability: Encourages logical separation of key rulesets, enabling ease of composition and mixing different domains and platforms
• Simplicity: Preserves the simple approach embraced by Openspec
• Modularity: Enables users and AIs alike to reference relevant information without overloading context
• Portability: Users can bring their kit with them to each new project and remix domains as required
• Shareability: Opens the opportunity to enable a directory or library of prebuilt rules for various domains and disciplines
• Efficiency: Avoids the need for explicit repetition of persistent ideas across projects, naturally accelerating progress

CHALLENGES

• Additional folders and functions should be carefully considered to preserve the purity of the OpenSpec approach
• Confusion: Users may find the presence of an empty or unexpected folder confusing at first
• Overthinking: Users may be tempted to over engineer their projects by splitting rules out unnecessarily
• Placing rules into separate files may make it more difficult for users to synthesise their project scope

[som45oul]

A minor footnote:

If implementing the slash commend option, perhaps using /openspec:rules (plural) is preferable for consistency. Main issue updated to reflect this.

[som45oul]

Also, perhaps the default openspec.rules.md could be the place where the Agent understands how to manage the rules? Main issue updated to reflect this.

[jasnzhuang]

Hey bro, have you considered pointing openspec to the project's CLAUDE.md or AGENTS.md instead?

[som45oul]

Hey bro, have you considered pointing openspec to the project's CLAUDE.md or AGENTS.md instead?

Not sure what you mean, however the point of this proposal is to separate out rules so they can be made portable, reusable and composable. That is, you might develop a typescript.rules.md that applies all the patterns you like / prefer for Typescript, and can then import that into your next project. You could also combine this with other rules files, such as react.rules.md or tailwind.rules.md to build up a collection of rules, rather than having to specify them all in one place uniquely each time.

The end result is you develop (and share) a library of rules.md files that can accelerate agentic development, since you don't have to repeat yourself with every project.

I hope that makes sense.

[j2h4u]

I think this proposal misses an important point about separation of concerns.

Rules are already handled by the IDE/coding environment layer (Cursor, Claude, Cline, etc.) through .cursorrules, .clinerules, CLAUDE.md, AGENTS.md and similar files. These tools already provide granular, portable, and composable rule management.

OpenSpec's job is to define the project structure and requirements, not to duplicate IDE-level functionality. If you need portable rules across projects, you should be leveraging your IDE's native rule system - that's literally what those files are for.

The comment about AGENTS.md / CLAUDE.md from @jasnzhuang is exactly on point -- these mechanisms already solve the problem you're describing. If OpenSpec starts managing rules, we're creating redundancy and coupling OpenSpec to IDE concerns.

Separation of concerns:

• OpenSpec - Project specification and structure
• IDE/Agent layer - Rules, conventions, coding style

This keeps OpenSpec focused and prevents it from becoming bloated with features that already exist elsewhere in the toolchain.

[som45oul]

You make a good point.

Except those things are not platform agnostic or composable.

Agent Skills however may be the right answer here. Albeit that the naming is a little awkward.