Rendered at 16:40:13 GMT+0000 (Coordinated Universal Time) with Cloudflare Workers.
mafro 6 hours ago [-]
I've used OpenSpec extensively on two large pieces of software which were worked solo over 6-9 months.
Recently, I've completely ditched the specification part. I found they just weren't useful over the longer term. I used an LLM to assess in both directions whether the code matched the specs and whether the specs matched the code. On both software projects this came out with huge divergence from spec to code.
Basically the old theory is true - the code IS the specification.
What I did find very useful and have retained is the process flow. Create a proposal, review the proposal, implement, review the code. Also useful was building and maintaining ADRs and invariant logs for where a unit test cannot be made to verify behaviour. The process and the ADRs, unit test, invariant log all help the software stay coherent as the LLM churns on it over many unconnected contexts.
sieve 4 hours ago [-]
> Basically the old theory is true - the code IS the specification.
The spec is whatever I write by hand. The code is what the LLM writes for me. The spec could be anything depending on how much detail you want.
The problem with the "code IS the spec" in the age of LLMs is that they will change stuff without telling you while hitting their immediate goal. Six months ago, I used to review every single change. Now I get the LLM to audit the code to compare against the spec. Any divergence means one of two things:
- either I have to update the spec, or
- the LLM has to update the code.
mafro 36 minutes ago [-]
I can appreciate your approach, but I'm not hand writing 100s to 1000s of specs by hand - at that point I'll just write the code myself
threatofrain 4 hours ago [-]
I don't think your dichotomy works. When an LLM is reaching into agents.md it is absolutely modifying the specs. Who cares about original providence when it ends up in agents.md?
cloverich 3 hours ago [-]
The reason the code is the specification is because people don't take specification seriously. Usually for good reason, but sometimes not. Real, long-lived RFC's can exist, and can have directional and corrective impacts on your LLM generated code. The trick is the RFC needs to be human written and maintained. The moment the org allows the LLM themselves to modify the spec... then yes the spec is no longer useful; or rather, "why" comments in code + a sliver of high level directional / summary content is probably all that is valuable.
A fun example can be having the LLM implement a well known spec (which it cannot edit), and then to use the spec in review to find mistakes and corrections. That's helped it really click for me. All these tools that let LLMs generate spec, even with iterative planning... I haven't found it useful for very long. It's great for building something complex in the very short term (e.g. days). But i haven't found keeping them afterwards to provide any benefit.
mactavish88 4 hours ago [-]
Agreed. Having used OpenSpec extensively for a few months now, long-lived specs in the repo are useless, but the OpenSpec change process is super valuable for keeping agents on track across a single complex project (e.g. developing a single complex new feature in a large codebase).
polycaster 5 hours ago [-]
The code is only part of the specification. It does rarely document the actual requirements to a degree you can rely on for decision making. Sure, the code should speak for itself, but it mostly speaks about the WHYs of the implementation, not the reasoning behind the actual requirement. I found that OpenSpec actually helps a lot in this regard.
mafro 31 minutes ago [-]
I challenge you to use a frontier LLM to analyse your code and specs and verify if they are meaningfully aligned.
Code almost never speaks to the WHY; ADRs will help there.
Code never captures requirements, but it does reflect actual system behaviour, which is a specification.
hmokiguess 2 hours ago [-]
I have been doing some greenfield work as a solo founder in a fully agentic workflow for a while now, and I mostly find these “frameworks” don’t work for me.
I am not yet convinced this space has been claimed in a way like say how “React” became the framework of choice in frontend development.
These initiatives all seem to tackle a “nice to have” or “quality of life” impact in the workflows in my opinion. Haven’t yet seen a proposal that addresses the larger problems, which, I think are even hard to quantify and explain still.
AI is great as a writing aid, still bad as a reading aid. To me the bottleneck remains the human and how can you help the human make better and more informed steering decisions backed by data driven and verifiable proofs against your system.
The organizing aspect of information feels like a step towards the bigger picture but not that much of a leap yet.
ricardobeat 6 hours ago [-]
The documentation is entirely about how to use it, how to manage the skills and configure it.
What I'd like to see is what it is, how and why it works, ideally backed by some benchmarks. Otherwise it looks like just another pile of skills with unknown outcomes.
twen_ty 8 hours ago [-]
Can someone tell me how this stuff is any different from the 90's let's use UML for code gen and how it's not going to fail in the same way?
In my experience, spec drift is the main reason why none of these tools work. Maybe they work for one shot greenfield feature generation but in a large, multi developer long lived code bases, specs rot and end up being more pain than they are worth.
wyum 2 hours ago [-]
I think modeling languages for code gen fall short because they aren't expressive enough and basically have to become programming languages and their users, programmers. This is the line of thinking that leads to "the specs are the code" conclusion.
I believe writing specs is different with AI for a few reasons: (1) natural language is expressive enough and the team collaborates at this level already, (2) LLMs can fill in the gaps, point out inconsistencies, and reliably map natlang to code, and (3) LLMs can read and refine specs at superhuman speeds, which makes spec maintenance economically viable for the first time ever outside of high stakes applications.
For this to work over the long run, specs must take a certain form. IMO: they must focus on original intent and what must be true after implementation (assertions) rather than implementation details. I also don't think one needs to specify anything an LLM can easily infer, so specs should be kept lean.
For spec drift, my team uses a sandboxed agent that checks for drift daily, triages, and surfaces issues. Beyond fixing specs, this has revealed a lot of product level miscommunications and helps us get ahead of them.
Why would you have a spec drift? My team has an AI review that matches the existing specs against the current implementation. This is very useful and keeps both in sync. If there are any conflicts they are noted in the pull request review and can be fixed. This works very nicely.
spinningslate 5 hours ago [-]
that's a good question. UML - at least the mainstream version pushed by e.g. Rational - failed for many reasons. A couple pertinent to this discussion:
1. Lack of closed loop between the "spec" and working code (your spec rot point). The Rational Unified Process(RUP) was a grossly inefficient, heavily manual undertaking. Mapping between artefacts - e.g. "Platform Independent Models" and "Platform Specific Models" was a manual, largely heuristic based approach. As a consequence the models were not generally kept up to date as the project evolved.
2. User experience mismatch. Developers were asked to create diagrams instead of writing code. Tool usability was poor ("write code with a mouse") and the artefacts didn't fit well with necessary tools like diffing and source code control (try diffing an xml file textually).
Coding agents have some potential for alleviating (1) in that they can read the result code and, at least to some extent, ensure spec and code are in sync.
(2) is more open. Some users - those proportionally more interested in solving the problem than designing/writing code - are more comfortable with natural-language-based specs and exploration. Those more experienced/comfortable with code will likely see those specs more akin to UML diagrams: a distraction from the real thing.
0x445442 4 hours ago [-]
This is what I've been mulling over for months. Surely there's a better, more rigorous specification format than Markdown prose that already exists in the industry and is useful to the agents. Formal Use Cases perhaps? Probably not Gherkin but maybe some other spec DSL.
twohaibei 8 hours ago [-]
I think the premise is that when agent modifies the code with human instruction explicitly saying spec has changed, the agent goes to the spec and updates it. But maybe giving it too much of credit and projecting what I think it should do.
postpriorx 7 hours ago [-]
The project evolution tracking argument does apply here, but another benefit is provides a standardized structure for planning and executing work that you can build your agentic code flows/loops around.
cg-enterprise 10 hours ago [-]
It's interesting to see the divergence of opinions on these frameworks and also at least anecdotally how many people roll their own custom implementations of workflow management on top of their favourite SDD framework.
I also ended up doing my own thing mainly to address several omissions in the existing frameworks (for SDD I prefer to use Superpowers and/or Matt Pocock's skills):
1. Artifact staleness and tracking - if you have a structure around starting with something like an ADR, common patterns for the whole repo etc., it's super hard to keep track of and actually keep it up to date. You make a strong early decision in an ADR and realize that you have to change it later on, or diverge. These changes get rarely properly recorded.
2. Review loop - Same model review isn't enough, I want bunch of models bouncing off each other, whilst still using my subscription and not API.
3. Feature creep and deferral tracking - it happens a lot that you encounter either during review or one of the validation phases that you also need to implement x, which is not covered by the original spec. There are several options to handle that, with the key that all those decisions need to be tracked and at some point decided by a human.
4. Custom workflow with governance - I have my own preferred SDLC if you can call it that, which includes rounds of agentic review of spec, before manual approval gate, review loop with certain specification depending on the codebase, feature size, deferral rules.
5. Ceremony based on context - Because it would happen that some of the ceremony would get in the way at some points (like producing a 100+ loc spec for 10loc change) I ended up basically developing a flow to decide whether a feature actually needs the full ceremony (full lane) or we can simply use the native plan feature (fast lane), so that I don't have to go through the whole ordeal of steps, when I need a tiny change.
What I prefer is to be able to iterate and iterate on my spec, then implement once. That’s what I’ve come to as a process with CC, and I’ve gotten really good results. Whenever I spend less than 20-30 minutes actively discussing the spec with the agent, the quality of implementation rapidly drops, even with some tiny things.
I like the overall idea of this, but the writing of the spec to me is more like building the thing than the implementation itself, and needs more active human (and agent) cycles.
sheepscreek 16 hours ago [-]
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.
crossroadsguy 14 hours ago [-]
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.
postpriorx 7 hours ago [-]
For teams its very helpful too, as you entire team standardizes around a common set of artifact for planning and executing work (with explicit semantics). Avoids snowflake agent sessions and artifacts for planning, proposing and executing work.
scosman 15 hours ago [-]
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
Wazzymandias 15 hours ago [-]
> been trained on enough long context tasks to have become pretty good at planning
This is absolutely not true
thesmtsolver2 14 hours ago [-]
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.
vintermann 8 hours ago [-]
At least for my personal projects, it's enough that they're better than me at long-horizon planning.
verdverm 14 hours ago [-]
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
philipp-gayret 9 hours ago [-]
I agree but your taste in making solutions, or that of your organisation may be very different from what an LLM does by default. I personally use specs to capture this taste; an example shared by most LLMs is that they like to document not only what they have built but also what they have not built. Especially after changing solutions or small migrations. Specifications can resolve most if not all of that behaviour.
loveparade 12 hours ago [-]
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.
visarga 12 hours ago [-]
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.
alexjplant 15 hours ago [-]
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.
14 hours ago [-]
jmathai 14 hours ago [-]
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.
virgil_disgr4ce 15 hours ago [-]
specifying is not planning
wyum 17 hours ago [-]
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:
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).
ulimn 7 hours ago [-]
Please don't take this as offense, I'm honestly curious as I'm pretty bad at these things.
You say this is your first time seeing openspec, but you've been working on a pretty similar project for a year now. Openspec and Speckit both seem to have similar (almost same?) goal as yours. Do you just jump into such a project as yours without worrying about others already existing?
I tend to overthink such stuff...
wyum 3 hours ago [-]
No offense taken. I'd also say I overthink things, so this question hits home.
The existence of similar tools has certainly given me pause several times. I was aware of SpecKit (GitHub) and Kiro (Amazon) when I started in January of this year. I Googled around and asked AI to find and evaluate similar things to my idea. Somehow I genuinely missed openspec, which seems to have had 20k GitHub stars at that time. I look at this and realize how bad I've been about sharing and promoting spekk.
I've continued to iterate on my idea because nobody else is as focused on the concept of declarative, living specifications that evolve with the code. From the beginning that has been Spekk's differentiator.
I've definitely had doubts about whether building my own version is "worth it."
Some wisdom I've gained as I get older is that the world is a complex place. There are many valid ways to solve the same problem, and every version has its audience and community.
The other thing is that even in this age of AI, putting sustained effort into a thing is still a scarce resource. The best software still takes time to mature and refine. It never ceases to amaze me how many small but important decisions and features go into what many see as "just markdown files and skills."
Appreciate the question.
diegolas 2 hours ago [-]
the workflows are still so scpecific to the individual that they all feel like a short blanket at some point, i have my own "framework" that i'm perfecting for my use case
wyum 1 hours ago [-]
I have the same feeling when I come across a new one. It's easy to throw something together that's good enough. That's why I open sourced spekk. I don't think there's a product here, just a way of thinking and doing I want to share.
FWIW, there are about ten people using Spekk at my agency daily. The standardization across people and projects is helpful to us. It's built for teams like us, not just me. There are definitely some features that took us a few weeks to months to get right, even AI assisted, and I think that has value whether you use our tool or ask your AI to copy parts of it.
We're a small team though, so your point still stands.
sroerick 12 hours ago [-]
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.
wyum 8 hours ago [-]
Thanks for having a look!
On removing cruft: one of the key features of spekk is an "observer" agent role that is tasked with finding drift. On a production codebase, I run this daily in a sandbox. It pulls the latest changes and looks for specs that are mismatched from the implementation, preferring to look at specs and code that changed recently and prioritizing "major" drift events. The observer agent then opens a PR wkth its observations (markdown with YAML like the specs). It also posts a summary to Slack, but that's optional. The sandbox agent code is part of the spekk-cli codebase.
passive 17 hours ago [-]
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. :)
makapuf 2 hours ago [-]
"easy not complex" I'm not completely convinced by this point : it's hard to stay simple ! Maybe I'm just nitpicking between simple vs easy, but words especially in such a context (language and specs expression) are important !
dmos62 9 hours ago [-]
Until LLM context sizes explode by two orders of magnitude, I cannot envision significant agent programming without leaning heavily on spec-driven workflows.
It's also worth noting that SDD is such a wide variety of approaches that the term on its own says very little. For example, SpecKit and SpecDD are both very capable SDD frameworks, yet they have only minimal overlap: SpecDD describes system components (with emphasis on boundaries), while SpecKit is a fairly advanced process for changing specs.
jmathai 16 hours ago [-]
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.
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.
jmathai 14 hours ago [-]
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.
open-paren 13 hours ago [-]
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.
nonethewiser 13 hours ago [-]
Trying to impose this kind of structure on the agent workflow creates more work and decreases quality. It's an illusion of control.
QwenGlazer9000 4 hours ago [-]
My org also adopted openspec, massive downgrade in workflow. Every change is so much more tedious now.
TabishB 11 hours ago [-]
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.
nicotejera 8 hours ago [-]
Been using it for a bit. I think its a matter of time until we dont look at code anymore and only look at specs, plans, design docs. I didnt like the doc organization (or lack of it) using a standard reader or editor, so I built one specifically for OpenSpec. Hope you find it useful https://specks.nicotejera.com
nullbio 5 hours ago [-]
Strongly disagree. I used to think the same thing, but I've slowly come to realize that we won't be looking at specs, we'll be asking an LLM to produce the specs in real time by reading code. Anything that causes drift from the code is a liability and a maintenance burden. Besides, what good are specs if they aren't reflective of reality? Do you know what is reflective of reality, though? The code.
nicotejera 4 hours ago [-]
In my experience, if I write good, thorough specs, the code adheres to them. And if something's off, I don't go and modify the code, this is when specs and code start to drift. The whole point about OpenSpec is that you create a new change, with a new spec, and then the LLM modifies the code accordingly. If you follow a process, I believe there's less risk of drift. But to each their own, you can obviously choose to own and author the code and have AI write the specs. For me, its more productive to write good specs, as I can write them faster and more people, sometimes not technical, can weigh in.
whinvik 7 hours ago [-]
Opened the link and it immediately shows how it generates so many files.
And my issue is always, how do I review so many files. Is the purpose just to go from 1 requirement prompt to so many spec files? How do I know the specs actually reflect the requirement?
I always feel I come away from projects like this even more confused.
gps372 11 hours ago [-]
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.
jochem9 11 hours ago [-]
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.
gps372 10 hours ago [-]
>> 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.
TabishB 11 hours ago [-]
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".
gps372 10 hours ago [-]
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.
pramodbiligiri 12 hours ago [-]
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.
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!
6 hours ago [-]
silvertab 17 hours ago [-]
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.
8cvor6j844qw_d6 16 hours ago [-]
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.
kaurimu 14 hours ago [-]
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.
[2] 100% auto-eliminating drift is an unrealistic goal -- that's where you come in.
iafiaf 3 hours ago [-]
Hi, your comment motivated me to try it out on my project. I'm looking for some advice.
I had a 2000 line specification, but no code yet. Based on lat.md, I have split the specification into 25 different files in the lat.md folder (not sure if that's too many).
My next task is to create a staged implementation plan, but I'm not sure how lat.md can help me (or is it even designed to?).
Should the implementation plan stages also be separate markdown files in the lat.md folder? Or a sub folder? (Does it matter).
My understanding is that lat will help create a knowledge graph between the specification files the implementation files, and the code.
chrismarlow9 16 hours ago [-]
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.
leemysw 11 hours ago [-]
[dead]
_blk 1 hours ago [-]
Interesting project. How does it compare to GSD (opengsd.net)? Just from the command set it seems a lot lighter but also less expressive.
GSD is quite OK but very token hungry (~4x but it buys traceability and has quite a powerful autonomous mode)
I use gsd-meta-manager to manage multiple GSD projects in parallel without having to use a skill to query each project individually to see where they're at. Does openspec have something like that too?
jeremyjh 17 hours ago [-]
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.
dmos62 10 hours ago [-]
Checkout SpecKit and SpecDD too. There is a significant variety of spec-driven development approaches.
nullbio 15 hours ago [-]
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?
broodbucket 13 hours ago [-]
If you're writing design documentation to /tmp you're not the target audience for this kind of thing
nullbio 5 hours ago [-]
No, I write design documentation to a docosaurus folder where it can actually be read as docs nicely.
Most of the time all you need is a throwaway md file to compensate for context loss and so you can loop on a spec across compaction. Once you have the spec implemented, there's usually no reason to keep it around. The code becomes the spec.
For hard constraints you have AGENTS.md, or put it in another md file. Why do I need additional software for this?
trollbridge 15 hours ago [-]
/tmp? What happens when you reboot?
nullbio 5 hours ago [-]
That's the entire point. Why would I want to keep these files around forever? If you're keeping these files you're just compounding drift onto drift and making it harder for the agent. For everything else, there is git history.
nonethewiser 13 hours ago [-]
You know
recroad 15 hours ago [-]
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.
chandlerklein 10 hours ago [-]
Would love to see a standalone binary, global Node installation is annoying
Mugshelf 16 hours ago [-]
Tired of wrestling JIRA for AI project specs. If this actually streamlines things, I'm definitely giving it a look.
evaltoken 15 hours ago [-]
Spec-driven workflows really seem to be where agent tooling is heading
slowmovintarget 17 hours ago [-]
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.
grohan 15 hours ago [-]
how are people currently evaluating between the different spec writing frameworks out there?
honkycat 16 hours ago [-]
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.
esafak 14 hours ago [-]
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.
wyre 17 hours ago [-]
It's just a bundle of skills and md files...
Why does it need to have an entire CLI?
iamjfu 16 hours ago [-]
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.
wyre 15 hours ago [-]
Compared to including shell scripts with the skills?
Not trying to say that it's not useful, but it seems excessive and potentially bloated.
etoxin 15 hours ago [-]
I use the cli tool outside of the agent session. e.g. `openspec view` to see all the specs and what's pending.
Recently, I've completely ditched the specification part. I found they just weren't useful over the longer term. I used an LLM to assess in both directions whether the code matched the specs and whether the specs matched the code. On both software projects this came out with huge divergence from spec to code.
Basically the old theory is true - the code IS the specification.
What I did find very useful and have retained is the process flow. Create a proposal, review the proposal, implement, review the code. Also useful was building and maintaining ADRs and invariant logs for where a unit test cannot be made to verify behaviour. The process and the ADRs, unit test, invariant log all help the software stay coherent as the LLM churns on it over many unconnected contexts.
The spec is whatever I write by hand. The code is what the LLM writes for me. The spec could be anything depending on how much detail you want.
The problem with the "code IS the spec" in the age of LLMs is that they will change stuff without telling you while hitting their immediate goal. Six months ago, I used to review every single change. Now I get the LLM to audit the code to compare against the spec. Any divergence means one of two things:
- either I have to update the spec, or
- the LLM has to update the code.
A fun example can be having the LLM implement a well known spec (which it cannot edit), and then to use the spec in review to find mistakes and corrections. That's helped it really click for me. All these tools that let LLMs generate spec, even with iterative planning... I haven't found it useful for very long. It's great for building something complex in the very short term (e.g. days). But i haven't found keeping them afterwards to provide any benefit.
Code almost never speaks to the WHY; ADRs will help there.
Code never captures requirements, but it does reflect actual system behaviour, which is a specification.
I am not yet convinced this space has been claimed in a way like say how “React” became the framework of choice in frontend development.
These initiatives all seem to tackle a “nice to have” or “quality of life” impact in the workflows in my opinion. Haven’t yet seen a proposal that addresses the larger problems, which, I think are even hard to quantify and explain still.
AI is great as a writing aid, still bad as a reading aid. To me the bottleneck remains the human and how can you help the human make better and more informed steering decisions backed by data driven and verifiable proofs against your system.
The organizing aspect of information feels like a step towards the bigger picture but not that much of a leap yet.
What I'd like to see is what it is, how and why it works, ideally backed by some benchmarks. Otherwise it looks like just another pile of skills with unknown outcomes.
In my experience, spec drift is the main reason why none of these tools work. Maybe they work for one shot greenfield feature generation but in a large, multi developer long lived code bases, specs rot and end up being more pain than they are worth.
I believe writing specs is different with AI for a few reasons: (1) natural language is expressive enough and the team collaborates at this level already, (2) LLMs can fill in the gaps, point out inconsistencies, and reliably map natlang to code, and (3) LLMs can read and refine specs at superhuman speeds, which makes spec maintenance economically viable for the first time ever outside of high stakes applications.
For this to work over the long run, specs must take a certain form. IMO: they must focus on original intent and what must be true after implementation (assertions) rather than implementation details. I also don't think one needs to specify anything an LLM can easily infer, so specs should be kept lean.
For spec drift, my team uses a sandboxed agent that checks for drift daily, triages, and surfaces issues. Beyond fixing specs, this has revealed a lot of product level miscommunications and helps us get ahead of them.
1. Lack of closed loop between the "spec" and working code (your spec rot point). The Rational Unified Process(RUP) was a grossly inefficient, heavily manual undertaking. Mapping between artefacts - e.g. "Platform Independent Models" and "Platform Specific Models" was a manual, largely heuristic based approach. As a consequence the models were not generally kept up to date as the project evolved.
2. User experience mismatch. Developers were asked to create diagrams instead of writing code. Tool usability was poor ("write code with a mouse") and the artefacts didn't fit well with necessary tools like diffing and source code control (try diffing an xml file textually).
Coding agents have some potential for alleviating (1) in that they can read the result code and, at least to some extent, ensure spec and code are in sync.
(2) is more open. Some users - those proportionally more interested in solving the problem than designing/writing code - are more comfortable with natural-language-based specs and exploration. Those more experienced/comfortable with code will likely see those specs more akin to UML diagrams: a distraction from the real thing.
I also ended up doing my own thing mainly to address several omissions in the existing frameworks (for SDD I prefer to use Superpowers and/or Matt Pocock's skills):
1. Artifact staleness and tracking - if you have a structure around starting with something like an ADR, common patterns for the whole repo etc., it's super hard to keep track of and actually keep it up to date. You make a strong early decision in an ADR and realize that you have to change it later on, or diverge. These changes get rarely properly recorded.
2. Review loop - Same model review isn't enough, I want bunch of models bouncing off each other, whilst still using my subscription and not API.
3. Feature creep and deferral tracking - it happens a lot that you encounter either during review or one of the validation phases that you also need to implement x, which is not covered by the original spec. There are several options to handle that, with the key that all those decisions need to be tracked and at some point decided by a human.
4. Custom workflow with governance - I have my own preferred SDLC if you can call it that, which includes rounds of agentic review of spec, before manual approval gate, review loop with certain specification depending on the codebase, feature size, deferral rules.
5. Ceremony based on context - Because it would happen that some of the ceremony would get in the way at some points (like producing a 100+ loc spec for 10loc change) I ended up basically developing a flow to decide whether a feature actually needs the full ceremony (full lane) or we can simply use the native plan feature (fast lane), so that I don't have to go through the whole ordeal of steps, when I need a tiny change.
I forked this code and added bits that matched my flow and it works out pretty well https://github.com/nutthouse/tutti
I like the overall idea of this, but the writing of the spec to me is more like building the thing than the implementation itself, and needs more active human (and agent) cycles.
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
This is absolutely not true
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
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 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).
You say this is your first time seeing openspec, but you've been working on a pretty similar project for a year now. Openspec and Speckit both seem to have similar (almost same?) goal as yours. Do you just jump into such a project as yours without worrying about others already existing?
I tend to overthink such stuff...
The existence of similar tools has certainly given me pause several times. I was aware of SpecKit (GitHub) and Kiro (Amazon) when I started in January of this year. I Googled around and asked AI to find and evaluate similar things to my idea. Somehow I genuinely missed openspec, which seems to have had 20k GitHub stars at that time. I look at this and realize how bad I've been about sharing and promoting spekk.
I've continued to iterate on my idea because nobody else is as focused on the concept of declarative, living specifications that evolve with the code. From the beginning that has been Spekk's differentiator.
I've definitely had doubts about whether building my own version is "worth it."
Some wisdom I've gained as I get older is that the world is a complex place. There are many valid ways to solve the same problem, and every version has its audience and community.
The other thing is that even in this age of AI, putting sustained effort into a thing is still a scarce resource. The best software still takes time to mature and refine. It never ceases to amaze me how many small but important decisions and features go into what many see as "just markdown files and skills."
Appreciate the question.
FWIW, there are about ten people using Spekk at my agency daily. The standardization across people and projects is helpful to us. It's built for teams like us, not just me. There are definitely some features that took us a few weeks to months to get right, even AI assisted, and I think that has value whether you use our tool or ask your AI to copy parts of it.
We're a small team though, so your point still stands.
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.
On removing cruft: one of the key features of spekk is an "observer" agent role that is tasked with finding drift. On a production codebase, I run this daily in a sandbox. It pulls the latest changes and looks for specs that are mismatched from the implementation, preferring to look at specs and code that changed recently and prioritizing "major" drift events. The observer agent then opens a PR wkth its observations (markdown with YAML like the specs). It also posts a summary to Slack, but that's optional. The sandbox agent code is part of the spekk-cli codebase.
It's also worth noting that SDD is such a wide variety of approaches that the term on its own says very little. For example, SpecKit and SpecDD are both very capable SDD frameworks, yet they have only minimal overlap: SpecDD describes system components (with emphasis on boundaries), while SpecKit is a fairly advanced process for changing specs.
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 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.
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.
And my issue is always, how do I review so many files. Is the purpose just to go from 1 requirement prompt to so many spec files? How do I know the specs actually reflect the requirement?
I always feel I come away from projects like this even more confused.
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.
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.
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.
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...
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.
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.
I had a 2000 line specification, but no code yet. Based on lat.md, I have split the specification into 25 different files in the lat.md folder (not sure if that's too many).
My next task is to create a staged implementation plan, but I'm not sure how lat.md can help me (or is it even designed to?). Should the implementation plan stages also be separate markdown files in the lat.md folder? Or a sub folder? (Does it matter).
My understanding is that lat will help create a knowledge graph between the specification files the implementation files, and the code.
```
~/.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.
GSD is quite OK but very token hungry (~4x but it buys traceability and has quite a powerful autonomous mode) I use gsd-meta-manager to manage multiple GSD projects in parallel without having to use a skill to query each project individually to see where they're at. Does openspec have something like that too?
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.
Most of the time all you need is a throwaway md file to compensate for context loss and so you can loop on a spec across compaction. Once you have the spec implemented, there's usually no reason to keep it around. The code becomes the spec.
For hard constraints you have AGENTS.md, or put it in another md file. Why do I need additional software for this?
It works fairly well, and it is definitely less heavy than SpecKit.
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.
Why does it need to have an entire CLI?
Not trying to say that it's not useful, but it seems excessive and potentially bloated.