I've been using this, or more pointedly, I built an agent fleet (bespoke harness) where the planner agent uses OpenSpec to generate the plan. Then turns the tasks into a ticket graph.
It works fairly well, and it is definitely less heavy than SpecKit.
This looks like exactly what I've been thinking I needed. I've tried Superpowers, GSD and oh-my-claude/openagent and mostly they burn more tokens.
Lately I've been using stock OMP and its close to the right balance but not quite enough of the brainstorming and spec maintenance built in. I've tried to layer some simple stuff on myself but with mixed results.
I think they might be in the process of re-designing the site and/or moving docs because it all used to work not that long ago, but the site design was completely different last time I checked.
Hey, maintainer here, the other reply got it right. We recently re-wrote the entire docs from scratch and we added some placeholders for other pieces of documentation we wanted to fill in, but it seems like some of the placeholder links stayed. Will update this!
Similar iterative specs philosophy. Ours is a bit different because we focus on declarative specs and installable agent skills. We chose Go for simplicity and minimal requirements (single binary).
I've also been building something like this, and browsing spekk-cli, it's interesting to see that we ended up with similar roles. Might be fun to compare and contrast a couple of these systems. :)
I did a similar thing. Yours seems cleaner than mine. I have a 'compiler' and a sexp based DSL. I don't know how anybody vibecodes medium or large programs, say above 50,000 lines of code. I don't read all the spec until I sense something is out of alignment.
Ive wondered if I have too much complexity, and from time to time I do a "prompt astrology reset" where I get rid of all the extra cruft. I can't go without the spec sheets though.
The CLI is actually useful. It gives the skills a way to deterministically interact with the spec. For example, it can validate the shape without having to spend tokens reading the files.
I am sorry but 471 lines is nothing in 2026. Come back when it has executed a 5000-10,000 line spec flawlessly, although the threshold keeps getting higher as the models get better. You're right though about a simple spec based workflow going far.
Yeah - I'm sure folks have pushed it further than I have. But this is what I've seen with my own eyes as opposed to read from others. And even at 471, I'm impressed.
Symlink the global MD files to a single file I control that is versioned. Define my own general spec and workflow terminology using markdown files in this universal MD.
```
~/.config/opencode/AGENTS.md
~/.claude/CLAUDE.md
~/.codex/AGENTS.md
~/.copilot/copilot-instructions.md
~/.gemini/GEMINI.md
```
Define it as a graph and iterate. I use more tokens, but I can also use more tools without disruption. Delegating markdown to folders/smaller repos can solve the tokens/context issue.
I settled on lat.md [1] at the beginning of this year and never looked back.
Its design offers a compellingly simple surface for weaving natural-language intent into the codebase itself, without overcomplicating things:
---
Key Ideas
* Plain markdown: readable by humans, parseable by agents
* Wiki links connect concepts into a navigable graph
* // @lat: and # @lat: comments tie source code to specs
* lat check ensures nothing drifts out of sync
* lat search for semantic vector search across all sections
---
For me it strikes the right balance between structure and flexibility. It gives agents enough context-efficient grounding to reduce functional and architectural drift [2], while remaining malleable enough to evolve with new requirements.
Admittedly I haven't run any evals, and I'm sure there are even better systems out there... but if I still had the problem I was trying to solve when I found it, I wouldn't be talking about it right now.
Of course it's likely that my problem has only migrated to a higher order of complexity, but surfacing it again through building increasingly complex things is an interesting enough challenge in itself.
Easily my favorite spec driven development framework.
It scored really well in our internal evals as well.
I think it has the most sane ceremony and its model fits my mental model really well.
I've also been working on a TUI that will automatically generate "phases" with each one being a openspec spec.
I would highly recommend trying out SpecDriven development. I found it to be the most productive way to work with LLMs for larger tasks, and I have found that it improves performance on larger tasks.
To me, this is where LLMs should go. Collaborating on shared documents that serve as a contract that then gets evaluated post-implementation
I've made multiple attempts to write domain-specific languages for LLMs to use to guide software architecture so that I can have higher-quality software architecture and also so that it can communicate ideas to me in a more terse way.
One thing that I think LLMs are lacking right now is information density. I'm a guitarist, and I like this game called Rocksmith, but I think that its user interface kind of sucks. It's fun to play along with the songs, and it's fun that it scores me on the songs and gamifies playing guitar. For dense notes, the user interface just isn't very good.
That kind of made me think more about information density. A sheet of notes is very dense, but it takes a little more time to process. Guitar tablature is slightly less dense, but I think it strikes a better balance between treble clef and Rocksmith. Really, I'd rather have all three of those presented to me.
This is really where I'd like to go with how I'm writing software now. LLMs: I'd love to be able to just create a specification that is very dense and describes domain-driven design concepts to the LLM, and then have a workflow that will do adversarial review to evaluate those concepts after implementing a phase.
This also kind of solves part of the problem with design decisions and artifact storage and all those things that we kind of see LLMs scatter around a codebase. If it exists in the spec, then it can be referenced later, and you can document changes, etc. Also, if you do the spec right, it could be language-agnostic.
Haven’t we moved on from these things? Most recent LLMs have been trained on enough long context tasks to have become pretty good at planning. Perhaps with contributions from the harness. In either case, I wouldn’t bother if I were using Codex or Claude Code.
They can plan, but no guarantee it will produce what you want. Sometimes most of the work is aligning on what to build. And I'm not handing over technical planning to it yet.
I use this skill and it makes the specing process progressive. Human driven for the "what", 50/50 for higher level technical planning, only where it has questions in the low level details: https://github.com/scosman/vibe-crafting
I bother because Claude Code does wacky nonsense unless I use OpenSpec (or something similar) to explicitly research, scope, persist, then implement in a brand-new context. Even Opus will do ridiculous nonsense like throw its hands up when asked to start a Docker container, ignore explicit architectural instructions, write verbose make-work documentation riddled with inaccuracies, etc. Using OpenSpec keeps things as constrained as possible with the side effect of recording what your system does.
OpenCode and various open models do not exhibit this tendency nearly as much in my experience. My recent experiences with GPT-5.6 were also very positive in this regard. Alas for regulatory reasons this stack is a non-starter at $DAYJOB so I'm stuck working around Anthropic's capacity optimizing shenanigans.
if anything in the latest batch, they have been trained to try everything and anything to get a task done, hence their hacking abilities, but also how they go way off the rails when they don't get sufficient context on our human intent for the task
feels less like planning and more like throwing spaghetti at the wall the moment ambiguity emerges, I really hope the next batch dials it back
Well, they are absolutely pretty good at faking being good at long-horizon planning which is enough to fool a lot of people till things start breaking lol.
Do you save the plans from plan mode alongside of the feature? I use specs to save the artifact but hadn't thought of using plan mode as the spec generator itself.
I mostly use speckit, not openspec. I think basically these are the same tools. There are other reasons for using such tools, but one reason is to enforce discipline for me and the LLM. Otherwise, often it starts going round in circles. Helps me save tokens as well. Again, the discipline is the important bit (along with clearly produced artefacts). Can I do all of this just with the LLM? Yes and that's what I did but it was very messy.
That's what I thought too. I used speckit quite a bit before and I've had mixed results at best. You are just moving ambiguity and code review from one place to another without really gaining anything.
I just rely on a log of user messages, all messages the user typed in a project as raw data and do a pass with agents to synthesize intent. Then use this for planning and validation of code. I think the user messages are the most valuable data in a project for this reason. Doing this reflection pass on messages takes just a few minutes even for thousands of messages. It keeps global perspective which is often lost in local work.
I use this to produce the task list which I then feed into a Ralph loop using a bash script. I save a lot of tokens since each tasks context is so small.
I just have it write a checklist file in /tmp (or a todo folder if I want to keep it), and check off items as it finishes them. Seems to work fine. Is this really needed?
Even OpenSpec is too heavy for me. I do similar things but in one file, which I generate with a skill after a planning session. The important thing is to have a file reviewers can audit the code against.
my org at work adopted openspec, and i strongly dislike it. every change, medium or larger, turns into a large set of multiple markdown documents, each that need review. and they are never handwritten - always slop, filled with the all the tells of ai writing, which i personally find grating.
i find a small, human written spec to be much more effective than these large spec documents.
the idea is that you iterate with your agent to write the spec, you implement, then eventually that spec gets merged into a "spec corpus" that describes all the behavior of the repository. but i don't think that prose can ever enumerate all the behaviors required of code, nor should it. the spec almost immediately becomes out of date.
Yeah I agree that if no thought or effort is put into the spec, it can turn into unreadable slop. We see a wide spectrum of specs, some more thought out than others. While quality(and readability!) of spec will still largely be on humans, there's things we want to do to improve this experience. We'll be updating the experience not too far away to make things a lot more succinct and iterative.
Either ways, we're open to feedback and I'm happy to have a conversation. Feel free to email me at tabish@openspec.dev to set something up.
I too felt the need for some structure around AI coding, and created a spec-based tool earlier this year: https://www.shipsmooth.net/. I'm happy using it. I think of it as "light-weight" and encouraging iterative development over specs+code. It creates just one spec file and one "tasks" file for each unit of work. Available as a plugin for Claude, Codex etc.
Looks like this will be a hard sell for many orgs who are already struggling with explosion of artifacts on JIRA, sharepoint, github, etc. Also, most of them have somewhat settled on some ways (in past 6-8 months) to produce AI first specs and work with them.
Also, this looks like something which leadership level folks need to adopt first and then somehow it needs to trickle down to PI planning and sprint planning. Would like to hear someone's experience on how this has got adopted in their org.
I use it at a much smaller scale. I think that's also the right place, because its a CLI tool + skills that generate md files. Not something you'd give to a business person. I start from a single ticket (sometimes just a handful of changes, but I want the spec as docs) to changes that you'd normally split over several tickets.
Basically the flow proposal -> design -> specs -> tasks gives you and AI a method to build context on what you want to achieve. In a way you're just creating a plan/big prompt that is structured in such a way that they start stacking on each other.
The power is that you do a lot of upfront thinking. In my team we then share it with a colleague who will review it through a PR. After that implementation is usually hands off. At the end there is a skill to verify the change against specs. I do still review the code myself too.
I guess if you work in a task oriented environment this will not work as well, as you'd lack/don't care about the business context. I'd like to think that most software development does not happen like this, but is done by engineers who actually understand why something is needed and take that into account when designing and building the solution.
> The power is that you do a lot of upfront thinking
This is the best part of this spec, but we have found from our experience that though upfront thinking changes has a lot of merits and adds clarity and alignment upfront, but it changes bit by bit in every meeting and before you know your specs are not aligned with general consensus in the team. If your team is large enough, then it gets very difficult to own the task of constructing alignment between your principal-artifacts and your evolved under-current of understanding.
I would still say that if you are working on a platform and if your engg team size if anything more than 25-30, then this spec must be adopted from top-down and not bottoms up. Bottom level engineers usually don't have the level of consistent exposures (as and when they socialize and evangelize their platform) which top level engineers have.
OpenSpec maintainer here. A lot of our adoption has mainly been bottoms-up, it's usually driven by engineers. That being said it definitely helps if everyone on the team uses it together. Especially when shifting left and doing a lot more "spec review".
Thanks for taking time to respond here. Would love to know from your experience the scale of function-points, team size, client-requirement variance, etc. different teams would have worked with and maintained over a period of time via this open-spec.
Please note that I can already see that github repo has 68k+ stars. So popularity is not in question, just the viability and consistency of adoption across different scenarios.
I've been using this, or more pointedly, I built an agent fleet (bespoke harness) where the planner agent uses OpenSpec to generate the plan. Then turns the tasks into a ticket graph.
It works fairly well, and it is definitely less heavy than SpecKit.
This looks like exactly what I've been thinking I needed. I've tried Superpowers, GSD and oh-my-claude/openagent and mostly they burn more tokens.
Lately I've been using stock OMP and its close to the right balance but not quite enough of the brainstorming and spec maintenance built in. I've tried to layer some simple stuff on myself but with mixed results.
This section https://openspec.dev/docs/setup links to "Concepts"
Concepts links here: https://github.com/Fission-AI/OpenSpec/blob/main/docs-lab/gu...
All the docs here are the templates rather than the actual file (I presume: https://github.com/Fission-AI/OpenSpec/blob/main/docs/concep...)
Somehow not very confidence inspiring...
I think they might be in the process of re-designing the site and/or moving docs because it all used to work not that long ago, but the site design was completely different last time I checked.
Hey, maintainer here, the other reply got it right. We recently re-wrote the entire docs from scratch and we added some placeholders for other pieces of documentation we wanted to fill in, but it seems like some of the placeholder links stayed. Will update this!
This is my first time seeing openspec, and it seems to share a similar philosophy to what I've been working on this year.
If you like this / SDD, I'd appreciate your feedback:
https://github.com/spekk-ai/spekk-cli
Similar iterative specs philosophy. Ours is a bit different because we focus on declarative specs and installable agent skills. We chose Go for simplicity and minimal requirements (single binary).
I've also been building something like this, and browsing spekk-cli, it's interesting to see that we ended up with similar roles. Might be fun to compare and contrast a couple of these systems. :)
I did a similar thing. Yours seems cleaner than mine. I have a 'compiler' and a sexp based DSL. I don't know how anybody vibecodes medium or large programs, say above 50,000 lines of code. I don't read all the spec until I sense something is out of alignment.
Ive wondered if I have too much complexity, and from time to time I do a "prompt astrology reset" where I get rid of all the extra cruft. I can't go without the spec sheets though.
It's just a bundle of skills and md files...
Why does it need to have an entire CLI?
The CLI is actually useful. It gives the skills a way to deterministically interact with the spec. For example, it can validate the shape without having to spend tokens reading the files.
Compared to including shell scripts with the skills?
Not trying to say that it's not useful, but it seems excessive and potentially bloated.
I use the cli tool outside of the agent session. e.g. `openspec view` to see all the specs and what's pending.
I have a super simple spec-based workflow. It works amazingly well. I’m amazed how well coding agents can work through what I consider large features.
Last week, I gave a 471 line spec to implement a major feature and it didn’t flinch. I wrote about it here.
https://jaisenmathai.com/articles/sojourn-for-ios-was-45-one...
I am sorry but 471 lines is nothing in 2026. Come back when it has executed a 5000-10,000 line spec flawlessly, although the threshold keeps getting higher as the models get better. You're right though about a simple spec based workflow going far.
Yeah - I'm sure folks have pushed it further than I have. But this is what I've seen with my own eyes as opposed to read from others. And even at 471, I'm impressed.
What are people using for this nowadays?
There seems to be a spectrum from fluid, iterative workflows like OpenSpec to more up-front alignment and control like Matt Pocock skills.
Curious what people have settled on.
Symlink the global MD files to a single file I control that is versioned. Define my own general spec and workflow terminology using markdown files in this universal MD.
```
~/.config/opencode/AGENTS.md
~/.claude/CLAUDE.md
~/.codex/AGENTS.md
~/.copilot/copilot-instructions.md
~/.gemini/GEMINI.md
```
Define it as a graph and iterate. I use more tokens, but I can also use more tools without disruption. Delegating markdown to folders/smaller repos can solve the tokens/context issue.
I settled on lat.md [1] at the beginning of this year and never looked back.
Its design offers a compellingly simple surface for weaving natural-language intent into the codebase itself, without overcomplicating things:
---
Key Ideas
* Plain markdown: readable by humans, parseable by agents
* Wiki links connect concepts into a navigable graph
* // @lat: and # @lat: comments tie source code to specs
* lat check ensures nothing drifts out of sync
* lat search for semantic vector search across all sections
---
For me it strikes the right balance between structure and flexibility. It gives agents enough context-efficient grounding to reduce functional and architectural drift [2], while remaining malleable enough to evolve with new requirements.
Admittedly I haven't run any evals, and I'm sure there are even better systems out there... but if I still had the problem I was trying to solve when I found it, I wouldn't be talking about it right now.
Of course it's likely that my problem has only migrated to a higher order of complexity, but surfacing it again through building increasingly complex things is an interesting enough challenge in itself.
[1] https://github.com/vercel-labs/lat.md
[2] 100% auto-eliminating drift is an unrealistic goal -- that's where you come in.
LOVE. LOVE. LOVE. Openspec.
Easily my favorite spec driven development framework.
It scored really well in our internal evals as well.
I think it has the most sane ceremony and its model fits my mental model really well.
I've also been working on a TUI that will automatically generate "phases" with each one being a openspec spec.
I would highly recommend trying out SpecDriven development. I found it to be the most productive way to work with LLMs for larger tasks, and I have found that it improves performance on larger tasks.
To me, this is where LLMs should go. Collaborating on shared documents that serve as a contract that then gets evaluated post-implementation
I've made multiple attempts to write domain-specific languages for LLMs to use to guide software architecture so that I can have higher-quality software architecture and also so that it can communicate ideas to me in a more terse way.
One thing that I think LLMs are lacking right now is information density. I'm a guitarist, and I like this game called Rocksmith, but I think that its user interface kind of sucks. It's fun to play along with the songs, and it's fun that it scores me on the songs and gamifies playing guitar. For dense notes, the user interface just isn't very good.
That kind of made me think more about information density. A sheet of notes is very dense, but it takes a little more time to process. Guitar tablature is slightly less dense, but I think it strikes a better balance between treble clef and Rocksmith. Really, I'd rather have all three of those presented to me.
This is really where I'd like to go with how I'm writing software now. LLMs: I'd love to be able to just create a specification that is very dense and describes domain-driven design concepts to the LLM, and then have a workflow that will do adversarial review to evaluate those concepts after implementing a phase.
This also kind of solves part of the problem with design decisions and artifact storage and all those things that we kind of see LLMs scatter around a codebase. If it exists in the spec, then it can be referenced later, and you can document changes, etc. Also, if you do the spec right, it could be language-agnostic.
Tired of wrestling JIRA for AI project specs. If this actually streamlines things, I'm definitely giving it a look.
Haven’t we moved on from these things? Most recent LLMs have been trained on enough long context tasks to have become pretty good at planning. Perhaps with contributions from the harness. In either case, I wouldn’t bother if I were using Codex or Claude Code.
They can plan, but no guarantee it will produce what you want. Sometimes most of the work is aligning on what to build. And I'm not handing over technical planning to it yet.
I use this skill and it makes the specing process progressive. Human driven for the "what", 50/50 for higher level technical planning, only where it has questions in the low level details: https://github.com/scosman/vibe-crafting
specifying is not planning
I bother because Claude Code does wacky nonsense unless I use OpenSpec (or something similar) to explicitly research, scope, persist, then implement in a brand-new context. Even Opus will do ridiculous nonsense like throw its hands up when asked to start a Docker container, ignore explicit architectural instructions, write verbose make-work documentation riddled with inaccuracies, etc. Using OpenSpec keeps things as constrained as possible with the side effect of recording what your system does.
OpenCode and various open models do not exhibit this tendency nearly as much in my experience. My recent experiences with GPT-5.6 were also very positive in this regard. Alas for regulatory reasons this stack is a non-starter at $DAYJOB so I'm stuck working around Anthropic's capacity optimizing shenanigans.
This is absolutely not true
if anything in the latest batch, they have been trained to try everything and anything to get a task done, hence their hacking abilities, but also how they go way off the rails when they don't get sufficient context on our human intent for the task
feels less like planning and more like throwing spaghetti at the wall the moment ambiguity emerges, I really hope the next batch dials it back
Well, they are absolutely pretty good at faking being good at long-horizon planning which is enough to fool a lot of people till things start breaking lol.
Do you save the plans from plan mode alongside of the feature? I use specs to save the artifact but hadn't thought of using plan mode as the spec generator itself.
I mostly use speckit, not openspec. I think basically these are the same tools. There are other reasons for using such tools, but one reason is to enforce discipline for me and the LLM. Otherwise, often it starts going round in circles. Helps me save tokens as well. Again, the discipline is the important bit (along with clearly produced artefacts). Can I do all of this just with the LLM? Yes and that's what I did but it was very messy.
That's what I thought too. I used speckit quite a bit before and I've had mixed results at best. You are just moving ambiguity and code review from one place to another without really gaining anything.
I just rely on a log of user messages, all messages the user typed in a project as raw data and do a pass with agents to synthesize intent. Then use this for planning and validation of code. I think the user messages are the most valuable data in a project for this reason. Doing this reflection pass on messages takes just a few minutes even for thousands of messages. It keeps global perspective which is often lost in local work.
Spec-driven workflows really seem to be where agent tooling is heading
how are people currently evaluating between the different spec writing frameworks out there?
I use this to produce the task list which I then feed into a Ralph loop using a bash script. I save a lot of tokens since each tasks context is so small.
I just have it write a checklist file in /tmp (or a todo folder if I want to keep it), and check off items as it finishes them. Seems to work fine. Is this really needed?
/tmp? What happens when you reboot?
You know
If you're writing design documentation to /tmp you're not the target audience for this kind of thing
Even OpenSpec is too heavy for me. I do similar things but in one file, which I generate with a skill after a planning session. The important thing is to have a file reviewers can audit the code against.
my org at work adopted openspec, and i strongly dislike it. every change, medium or larger, turns into a large set of multiple markdown documents, each that need review. and they are never handwritten - always slop, filled with the all the tells of ai writing, which i personally find grating.
i find a small, human written spec to be much more effective than these large spec documents.
the idea is that you iterate with your agent to write the spec, you implement, then eventually that spec gets merged into a "spec corpus" that describes all the behavior of the repository. but i don't think that prose can ever enumerate all the behaviors required of code, nor should it. the spec almost immediately becomes out of date.
Trying to impose this kind of structure on the agent workflow creates more work and decreases quality. It's an illusion of control.
Yeah I agree that if no thought or effort is put into the spec, it can turn into unreadable slop. We see a wide spectrum of specs, some more thought out than others. While quality(and readability!) of spec will still largely be on humans, there's things we want to do to improve this experience. We'll be updating the experience not too far away to make things a lot more succinct and iterative.
Either ways, we're open to feedback and I'm happy to have a conversation. Feel free to email me at tabish@openspec.dev to set something up.
I too felt the need for some structure around AI coding, and created a spec-based tool earlier this year: https://www.shipsmooth.net/. I'm happy using it. I think of it as "light-weight" and encouraging iterative development over specs+code. It creates just one spec file and one "tasks" file for each unit of work. Available as a plugin for Claude, Codex etc.
Looks like this will be a hard sell for many orgs who are already struggling with explosion of artifacts on JIRA, sharepoint, github, etc. Also, most of them have somewhat settled on some ways (in past 6-8 months) to produce AI first specs and work with them.
Also, this looks like something which leadership level folks need to adopt first and then somehow it needs to trickle down to PI planning and sprint planning. Would like to hear someone's experience on how this has got adopted in their org.
I use it at a much smaller scale. I think that's also the right place, because its a CLI tool + skills that generate md files. Not something you'd give to a business person. I start from a single ticket (sometimes just a handful of changes, but I want the spec as docs) to changes that you'd normally split over several tickets.
Basically the flow proposal -> design -> specs -> tasks gives you and AI a method to build context on what you want to achieve. In a way you're just creating a plan/big prompt that is structured in such a way that they start stacking on each other.
The power is that you do a lot of upfront thinking. In my team we then share it with a colleague who will review it through a PR. After that implementation is usually hands off. At the end there is a skill to verify the change against specs. I do still review the code myself too.
I guess if you work in a task oriented environment this will not work as well, as you'd lack/don't care about the business context. I'd like to think that most software development does not happen like this, but is done by engineers who actually understand why something is needed and take that into account when designing and building the solution.
This is the best part of this spec, but we have found from our experience that though upfront thinking changes has a lot of merits and adds clarity and alignment upfront, but it changes bit by bit in every meeting and before you know your specs are not aligned with general consensus in the team. If your team is large enough, then it gets very difficult to own the task of constructing alignment between your principal-artifacts and your evolved under-current of understanding.
If you check my submissions (https://news.ycombinator.com/submitted?id=gps372), I have written whole set of articles on the myths of how easy it is keep the understanding consistent.
I would still say that if you are working on a platform and if your engg team size if anything more than 25-30, then this spec must be adopted from top-down and not bottoms up. Bottom level engineers usually don't have the level of consistent exposures (as and when they socialize and evangelize their platform) which top level engineers have.
OpenSpec maintainer here. A lot of our adoption has mainly been bottoms-up, it's usually driven by engineers. That being said it definitely helps if everyone on the team uses it together. Especially when shifting left and doing a lot more "spec review".
Thanks for taking time to respond here. Would love to know from your experience the scale of function-points, team size, client-requirement variance, etc. different teams would have worked with and maintained over a period of time via this open-spec.
Please note that I can already see that github repo has 68k+ stars. So popularity is not in question, just the viability and consistency of adoption across different scenarios.