OpenSpec Workflow Diagram

[harikrishnan83]

The diagram above focuses on the files generated during a change, in addition to the basic workflow already documented in OpenSpec’s README. If you spot any gaps or improvements in the above diagram, I am happy to be corrected.

UPDATE: Here is a related write-up.

UPDATE 2: Video walkthrough

[MRiabov]

oh. I personally didn't understand the "archive" part - I thought it was for deleting unnecessary ones only. Make sense!

[harikrishnan83]

I really like archive, the only thing I am trying to figure out now is how to make this work in a team where several proposals are in progress in separate branches.

[icaroryan]

How could we start a project from the very start? We'd still use the propose changes? I'm struggling a bit to understand that part. I was looking for a setup where I can pass in my PRD and it'd create the proposals for it

[icaroryan]

Hey @harikrishnan83,

Thank you for your response! The way I've been using it recently is just how you described, by splitting the whole PRD in smaller sets and creating proposals from those, but it'd be great if we could do it all at once. This framework is perfect for brownfield projects, but I still struggle a bit to use it for greenfield ones.

In this case, the PRD would be a document that outlines all aspects of the application, including goals, user stories, key acceptance criterias, etc (the one you're used to). My concern with doing one proposal at a time is that it wouldn't take into consideration the system as a whole, since it doesn't know about the other features yet.

I've read your linkedin post, and I totally agree! The main difference I noticed between OpenSpec and Spec-Kit was exactly related to this concept of mountains of markdown exactly because we're trying to design and plan the whole system at once, instead of at smaller, more manageable parts.

Maybe a good middle ground here would be to follow your advice in "Fully specify features in a line or two" and add it in projects.md just so the framework have in the back of its mind that these other features will be coming up eventually and the implementation doesn't become a frankenstein.

[harikrishnan83]

Hello @icaroryan , thanks for taking the time to go through my LinkedIn article. Glad it helps.

My concern with doing one proposal at a time is that it wouldn't take into consideration the system as a whole, since it doesn't know about the other features yet.

This is really important. With Spec Kit I have had difficulty in this area because there is no cross-feature analysis. However on OpenSpec, when I propose a new change the LLM, to the best of my understanding and experience, lists all existing features, and is reading the "source of truth" spec and then deciding on the delta / change. So at least it does take care of features historically. That said yes I am also trying to figure out how to give context on where we are headed.

I guess calling these out in the Discord channel will certainly help this project and others who may also have these questions.

Regards.

[royling]

This framework is perfect for brownfield projects, but I still struggle a bit to use it for greenfield ones.

Same struggling here. The simple question to me is: should I use OpenSpec for starting a greenfield (0 -> 1) project?

[icaroryan]

@royling If it helps, here's a thread on discord about this question: https://discord.com/channels/1411657095639601154/1437291115693998090

Question:

Hey guys quick question. I'm a beginner with Openspec and I was wondering how I'd use it to start a project from scratch? Do I just add my PRD to projects.md and ask it to create proposals off that? Or do I have to create proposals for every feature manually?

Answer

It depends on how big your PRD is. If it's relatively small you can directly create a proposal from the PRD.
If it's medium-large, reccomend creating a high level roadmap for yourself in a ROADMAP.md from the PRD. Then create proposals one at a time as you go. I don't reccomend trying to create all your proposals at the start, do it as you go and as you learn things.

[royling]

Thanks for the link, that's helpful.

[rosmur]

was this invented from scratch or within context/information/review of prior art?

Change management is a very very common workflow in many industries. It behooves us to review and adopt patterns that already exist, are real world proven, have worked well and battle tested.

[MRiabov]

@harikrishnan83 It would be better if this was enclosed into a video. I think one of reasons I had success with speckit was that it was easy to dive into - 20 minutes and you are in. With OpenSpec I couldn't understand what's going on and reverted the entire OpenSpec branch after 2 hours of "how do I introduce a new, small, self-contained feature here??".
Notably I'm at the 0-1 phase, closer to 1 now. (In particular, I tried having OpenSpec do a deployment for a data processing pipeline)

[TabishB]

Hey @MRiabov would be keen to learn, what part was confusing / hard to understand? Looking for feedback on where I can simplify the workflow here. My goals is to aim for processes that hopefully "just make sense" rather than needing lots of material to explain them (because at the root it probably means it's too complicated).

[MRiabov]

Hello. Well, I think I understand it a bit better now, but nevertheless:
Suppose we spec a feature. Let's say we want to make a distributed deployment of a application that we have just finished coding (as it is/was in my case).
So we specify what we want: we have a new application "controller" controlling the execution of the application that we have just coded up.

Right.

So I've got lost on this step. Openspec has "changes", but how do I actually implement it? In spec-kit I had non-technical spec, a technical plan, and execution tasks for a LLM. + checklists and /analyze to make sure you didn't underscope your application (was extremely useful to me just yesterday).

So where do I see and verify which features the LLM has to make? Tasks that it can check off?

The plan that openspec has generated led to model cycling in one spot for me and ultimately failing.

Anyhow... I get speckit. I couldn't get openspec, and it wasn't worth my time to investigate further.

Maybe I just didn't get it. In spec-KIT I had two 20-minute long videos that I watched and knew everything about the service..

---

Side note: there is also a Community-maintained spec-kitty which seems to have introduced interesting features. Looking into it rn.

--
Also, another critical thing to note: many changes arise as a result of debugging. E. G. My service didn't register something due to race conditions, so we added a completely new API that would ensure it would work.

I am thinking of a "/debug" command which would:

1. Fill up agent with context
2. Have it record its edits.

For now, I am doing
"""
There is a plan in @plan.md. There is a [malfunctioning behavior XYZ] and [4 lines of text describing the intention.]

Also, update the @plan with this intention please.
"""

Feels like debugging should be more optimal?

[icaroryan]

Hey @MRiabov, isn't the implementation done with the /apply command? Not sure if I fully understood your question. But you can implement the spec created by running this command

[harikrishnan83]

@MRiabov Thanks for the suggestion to create a video. I have recorded a walkthrough - https://youtu.be/B7VPMKW5tnk?si=3FJFLdg54RywVNFe. Hope this helps.