Use dot folder instead of root folder for OpenSpec #449
Description
CHANGE TYPE
Moderate effort - potentially breaking change
PROBLEM
Currently, OpenSpec uses the /openspec folder to maintain its register of SDD work. According to @TabishB, this is because - historically - some agents did not "play well" with a dot prefix (.openspec).
However, using a proprietary non dot folder is generally discouraged for tools, and dot folders are a fairly standard implementation for such functionality.
Having a proprietary folder in the root pollutes project clarity and deviates from what most tools typically do (.vscode, .github, .speckit, etc).
PROPOSAL
Default to using a dot folder (.openspec) in place of the current openspec root folder.
Recommend referring to other projects like Spec Kit, where use of dot folders is a "solved problem".
An interim -- option could be introduced for legacy support or to use the new structure, providing optionality for developers.
Ideally, renaming the openspec folder to .openspec in existing projects would be sufficient, however agent instructions may need to account for such a change.
BENEFITS
- Brings OpenSpec into line with common practice
- Clearly separates OpenSpec folders from project folders
- Places the OpenSpec part of the repo closer to the top of folder listings for easy reference
- Reduces the chances of the openspec folder being confused with the codebase itself
CHALLENGES
- Historically, some agents have not done well with dot folders, struggling to find the correct location
- This would be a potentially breaking change, meaning updates would need to preserve the "legacy" openspec folder where it exists
- This change would require fairly extensive testing to ensure it works with all the different AI tools, although solving for one will likely solve for many