Why I dropped OpenSpec for a few thin spec skills

I like writing the spec before the prompt. Asking an agent to "add bulk actions to the table" and hoping for the best produces something plausible and wrong. Writing down what done looks like first produces something close.

So I tried a proper framework for it. OpenSpec is a good one, and plenty of people get real value from it. I lasted a little while, then replaced it with a few small skills of my own. Here's why.

#The ceremony was bigger than the change

Most of my changes are small. A new filter, a copy tweak, a field on a form. A framework built around proposals, spec deltas and archiving is designed for changes that deserve that structure, and I kept feeling the weight of it on the ones that didn't.

I'd end up with more files describing the change than lines of code changing. And I'd catch myself skipping the process for small work, which meant the process only covered the work that needed it least to be written down.

#What I use instead

Two or three skills. One turns a rough idea into a short spec: the goal, what is out of scope, a few decisions and a checklist of tasks. One picks up that checklist and ticks things off as the work lands. One updates the spec when a decision changes mid-flight.

That's it. The spec is a single file, it lives next to the feature, and the task list is just checkboxes. The agent reads it, works through it, and I can see progress at a glance. If I want to skip it for a one-line fix, nothing stops me.

#Old specs are not free

This is the part I didn't expect. A spec is useful while the feature is being built. Six months later it describes what you intended, not what shipped, and the two drift apart.

The trouble is that agents find files. A stale spec sits in the repo, an agent searching for context stumbles over it, and now it's reading confident, out-of-date instructions as if they were current. It then builds on them. The failure is quiet, because nothing errors. The code just goes a little sideways.

I now treat specs as scaffolding. Useful while the building is happening, and then either deleted or reduced to a short note about decisions that still matter.

#It works better in small repos

In a small repo, a handful of specs stays easy to hold in your head. In a large one, the specs multiply faster than anyone can keep them accurate, and the staleness problem gets worse with every feature. I'm not sure there's a clean answer there yet. Pruning and ownership help, but they're discipline, not a fix.

#Where I want to take it

The part I find most interesting is taking myself out of the middle. I'd like an automated setup where I only approve two things: the spec at the start and the finished implementation at the end. In between, agents plan, build, check their own work and open the pull request.

I'm not there yet, and I'd be cautious about claiming otherwise. But thin skills suit that direction better than a heavy framework. A short, plain spec is something an agent can write and a human can approve in a minute.

If you're starting out, I'd begin with the lightest thing that could work: one file per feature and a checklist. Add structure only when you notice a specific problem it would solve.