Why I dropped OpenSpec for a few thin spec skills

I write the spec before the prompt. "Add bulk actions to the table" on its own gets me something plausible and wrong. Half a page on what done looks like gets me something close.

When I wanted a bit more structure around that habit, I tried OpenSpec. It's a well-made tool and plenty of people like it. I lasted a short while, then wrote my own small skills instead.

#What a fresh init gives you

Run openspec init in an empty repo and you get fifteen files before you've described anything: six skills, six slash commands, a config file and a couple of placeholders. The terminal in the image at the top has the full list. There are commands to propose a change, apply it and archive it.

That's a fair amount of structure for a change that deserves it. Most of mine don't. A new filter, a reworded label, a field on a form. I was writing more markdown about the change than I was changing code, and I caught myself skipping the process for small jobs. So it only covered the work that least needed it.

#What I use now

Three small skills. One turns a rough idea into a short spec: goal, out of scope, decisions and a checklist of tasks. One works through the checklist and ticks things off. One updates the spec when a decision changes halfway through.

A spec is a single markdown file next to the feature, like the one in the image. The agent reads it, I can see progress at a glance, and for a one-line fix I just don't write one.

#Old specs do damage

This is the part I didn't see coming. A spec is useful while you build. Months later it describes what you meant to build, and the code has moved on.

Agents go looking for context. They find the old spec, read it as current, and build on it. Nothing errors. The code just drifts a little sideways, and you only notice later. So I treat specs as scaffolding: delete them once the feature has shipped, or cut them down to the few decisions that still matter.

It's also why this works better in small repos. A handful of specs is easy to keep honest. In a big repo they multiply faster than anyone can maintain them, and I don't have a good answer for that yet. Pruning helps, but it's discipline, not a fix.

#Where I want to take it

I'd like to be out of the middle. Ideally I approve two things: the spec at the start and the finished implementation at the end, and agents handle the planning, building, checking and pull request in between. I haven't built that yet. But a short, plain spec is something an agent can draft and I can approve in a minute, which a heavier process makes harder.

If you're starting out, use one file per feature and a checklist. Add structure when a specific problem asks for it.