Feedback request: architecture decision records support

[eamonnfaherty]

Firstly, I love this project. Thank you to all the contributors.

I have been building a solution to the same problem and have found supporting architecture decision records has been very beneficial.

In my work, ADRs are key decisions about which software and infrastructure dependencies should be taken. They are suggested, reviewed and then approved.

In this project these details are added to the project file.

I would like to migrate to OpenSpec and was wondering how you felt about supporting ADRs in this way. I am happy to submit a PR but wanted to check in first.

[oleborne]

Did you try to point to the folder with your ADR from your project.md file?

[eamonnfaherty]

Thanks for the quick response. I initially thought that as a simple integration. I was after more of a generate, review, approve style workflow where ADRs are a first class citizen. I think ADRs could cover many non functional requirements to complement the specs which would cover the functional specs. As such I think they would benefit from a similar workflow.

[eamonnfaherty]

I raised a PR with the openspec changes https://github.com/Fission-AI/OpenSpec/pull/566/files

I think this does a pretty good job of explaining why this is needed and what the changes would be.

[oleborne]

I think you are actually hitting one of the current short comings of OpenSpec (in my eyes): it defines the Plan/Apply workflow but is missing the Research phase that is critical in the RPI (Research/Plan/Implement) workflow. The saying is that "if 1 line of plan will influence 100 lines of code, 1 line of research will influence 100 lines of plan".

ADR typically belongs to the research phase, when we analyze the current state of the project and past decisions that shaped it this way.

[eamonnfaherty]

@oleborne I agree with your point on 1 line of research will influence 100 lines of plan. I mostly work with large enterprises where architectural decisions are often made by central groups instead of application developers. In these cases the suggestion I have made in the PR makes sense. Where application developers have the decision making ability I agree the Research/Plan/Implement workflow makes a lot of sense.

[eamonnfaherty]

I have updated the PR, during spec creation workflow the agent will check for potential ADRs and suggest the review / create workflow. An OpenSpec change can contain specs and ADRs.

I think this may cover both use cases.

It is not a full research/plan/implement workflow and I do not think it blocks it.

[TabishB]

Hey all loving the discussion here.(@eamonnfaherty, @oleborne )

Currently OpenSpec serves a large amount of users all the way from hobby devs using it for side projects all the way to enterprise teams using it professionally day to day to deliver features.

This poses a challenge for us since we have to serve a wide variety of needs. We could simply say no to one demographic or the other, but I don't think it needs to be that way.

What we need is a higher degree of configuration and flexibility. We should try and provide a very lightweight default out of the box experience so people can easily get started with OpenSpec. Then if they choose they should have a pathway to start editing the config to make OpenSpec more complex.

We're already trying this in practice with some of the new configurable schema mechanisms where people can create their own schemas that define the types of artifacts they want to generate as well as the instructions and templates used to generate them.

For example a frontend team from ByteDance here has defined a new sdd schema for themselves that includes a design review document.

#536

Would a frontend design review document, make sense for most most people? Probably not, but they have the option to configure OpenSpec to make it work for them.

This is how I think we should be thinking about OpenSpec where we can provide a very simple, lightweight experience out of the box but allow for configuration that makes it infinitely hackable. This obviously does mean larger engineering complexity but I think it's worth it!

* when it says schema fork it means using the schema command to create a fork (not forking openspec itself)

[TabishB]

@eamonnfaherty That was a very long winded way of me saying yes I do like the idea of ADR's but this probably should not be the default experience. I think we need to figure out a way to make these kinds of things configurable such that users can define their own way of storing specs, ADR's etc.

I would try and look at the schema mechanics we currently have in place to see if we can extend this to make the source of truth storage configurable. (Feel free to dm me on discord with any questions).

[eamonnfaherty]

Thanks for the high quality response. I really appreciate it.

Instead of having specs and ADRs as different artifacts are you suggesting a route where we have specs plus any number of user defined artifacts. In that case users can define ADRs as an artifact type?

If so, I agree in principle but I worry if exposing it to users and asking them to configure it for each project would create too much load on them. I love the simplicity of getting started with OpenSpec and would not want to create barriers to entry.

I can see the need for other types of artifacts like ADRs - eg governance requirements, design style guidelines and more. To build each in the same way as ADRs (as I proposed) would be wasteful.

I do think there are two classes here - functional and non functional specs. How would you feel about an approach where users could easily define their own type of non-functional spec (through some configuration) in addition to supporting ADRs as an example of this non functional spec? Providing an example would help others create their own.

[TabishB]

@eamonnfaherty

In that case users can define ADRs as an artifact type?

yes! except it would be a source of truth artifact type I guess? Currently we only support configuration of "planning artifacts"

(horrible sketch below)

to configure it for each project would create too much load on them

yes hopefully we can make this a simple process and even provide some examples for them. And yes we can definitely provide ADR as an example.

For example just to test the limits of OpenSpecs configuration system, I added a TDD approach using a OpenSpec schema here: https://github.com/Fission-AI/OpenSpec/tree/main/schemas/tdd

I don't reccomend using it, it was more to see how crazy we could get with this approach.

The goal with schemas is to allow us maintainers to experiment with different approaches to see what works well as well as allow the community to experiment and iterate on what works well for them.

Eventually we want to open this up so these become easily shareable in the community and within teams etc

so maybe in the future we can have:

.
└── schemas/
    ├── openspec-default # current standard flow
    ├── openspec-ultralight # super minimal 1 markdown file flow
    └── community-enterprise # more enterprise-y version (maybe with ADR's?) 

which people can then install with openspec schema install community-enterprise (but this is a future concern)

but yes would be happy to support any number of community submitted schemas where people share what type of workflow is working for them. For community submitted schemas, these should not even need a maintainer approval - just share how you like your flavour of OpenSpec.

User should be allowed to fork the submitted schemas too, to tune it to their liking.