Planning. Arguably one of the most undervalued aspects of AI-assisted development. We’ve all been there - you fire up your AI coding agent, describe what you want, and before you know it you’re staring at a pile of generated code that technically works but doesn’t quite fit the bigger picture. What if there was a way to think things through before the code starts flowing?
What we will be covering
I am going to take you along with my experience using OpenSpec , a lightweight spec-driven framework that acts as a universal planning layer for AI coding agents. If you’re using tools like Claude Code, Cursor, GitHub Copilot, Gemini CLI or any of the other 30+ supported agents, OpenSpec slots right in. It’s open source, requires no API keys and does not depend on MCP, which means you can get started with minimal friction.
We will be looking at:
- What OpenSpec is and why you’d want to use it
- The core workflow: proposals, specs and tasks
- How specs provide persistent context across sessions
- Why reviewing intent beats reviewing code
The problem with prompt-and-pray
If you’ve worked with AI coding agents on a mature codebase (and let’s face it, most of us are not building greenfield projects every day), you’ve probably noticed how context gets lost between sessions. You explain something to your agent, it generates code, and the next time you pick things up you’re starting from scratch. There is no shared memory of why a decision was made, just the code it produced.
This is where OpenSpec comes in. It positions itself as a brownfield-first tool - designed for existing, mature codebases rather than fresh projects. The idea is simple: capture your requirements in specification files that live in the repository alongside your code, providing a persistent layer of context that any agent (or developer) can reference.
How it works
Getting started is straightforward. Install it globally:
1npm install -g @fission-ai/openspec@latest
The core workflow revolves around proposals. When you want to make a change, you describe it:
/openspec:proposal Add remember me checkbox with 30-day sessions
OpenSpec then searches your existing specs for relevant requirements, reads related files in your codebase, and generates a full proposal package. This package includes:
- proposal.md - a description of the change
- design.md - technical decisions and trade-offs
- tasks.md - implementation tasks broken into phases
- spec deltas - showing how system requirements change
All of this happens before you write a single line of code. The idea is to spend ten minutes thinking things through rather than an hour untangling something that went sideways.
Specs as living documentation
What’s nice about this approach is that your specifications live directly in the repository, organized by capability:
openspec/specs/
├── auth-login/spec.md
├── auth-session/spec.md
└── checkout-payment/spec.md
This means they travel with your code through branches, pull requests and merges. When a new developer joins the team, they can browse the spec library to understand how the system works and why certain decisions were made. No more digging through old Slack threads or Confluence pages that haven’t been updated since last year.
Persistent context matters
Unlike the built-in “plan mode” that some agents offer, OpenSpec’s context survives beyond a single chat session. The next time you (or a colleague, or a different agent entirely) picks up the work, the specs are right there in the repo. This is especially valuable when working across sessions or handing off work between team members.
Reviewing intent, not just code
This is probably my favourite aspect of OpenSpec. When you create a proposal, it generates spec deltas - documents that show how the system’s requirements change as a result of your modification. Instead of a reviewer having to parse through raw code changes to figure out what you were trying to achieve, they can look at the spec delta and immediately understand the intent.
This shifts the review conversation from “what does this code do?” to “is this the right change to make?” - which is where the valuable discussion should be happening in the first place.
What’s coming next
The team behind OpenSpec is currently building Workspaces, aimed at team collaboration. This will tackle challenges around large codebases, multi-repository planning, and deeper integration and customization options. If you’re working with a larger team, this is worth keeping an eye on.
Conclusion
OpenSpec fills a gap that I didn’t fully appreciate until I started using it. The pattern of thinking through changes before implementation isn’t new, but having a structured, agent-agnostic framework that makes this practical in an AI-assisted workflow is genuinely useful. The fact that specs live in the repo and work across any coding agent means there’s very little vendor lock-in and very little process overhead.
If you’re serious about maintaining quality in AI-assisted development (and you probably should be), it’s worth giving OpenSpec a try. Install it, run a proposal on your next feature, and see if the resulting structure helps you catch misalignment before it turns into rework.