DEV Community: Syed Ibrahim

OpenSpec: The Missing Layer Between You and Your AI Coding Assistant

Syed Ibrahim — Mon, 15 Jun 2026 13:14:35 +0000

If you have spent any time doing AI-assisted development or vibe coding, you already know the problem.

You open a new chat.
Start building something.
The AI just runs with it.

No alignment, no scope, no shared understanding of what you are actually trying to do.

That works fine for small throwaway tasks. But when you are working on a real codebase, things go sideways fast.

The AI makes assumptions. Scope creeps. You end up with code that technically works but does not match what you had in mind.

OpenSpec fixes this by introducing one simple idea

agree on what you are building before any code gets written.

It gives you and your AI coding assistant a lightweight structure to follow for every change you make. Before implementation starts, you define the intent, the scope, and the approach. The AI reads that and works within those boundaries instead of guessing.

The result is more predictable output, less back and forth, and something that matters a lot in fast-paced development ~ the reasoning behind your decisions is actually preserved instead of disappearing into chat history.

What is OpenSpec?

OpenSpec is a spec-driven development framework. It sits between you and your AI coding assistant as a lightweight planning layer.

The idea is simple. Before your AI writes a single line of code, you and the AI agree on a spec. What you are building, why you are building it, how you are going to build it, and what is out of scope. Everything is written down and locked in before implementation starts.

It works with the tools you already use ~ Claude Code, Cursor, Codex, Copilot, Antigravity and more. No API keys, no complex setup. Your specs live right inside your repository as markdown files.

Every change you make in OpenSpec goes through four artifacts:

Proposal ~ the why. What you want to build and why it matters
Specs ~ the what. The requirements and expected behavior
Design ~ the how. The technical approach and decisions
Tasks ~ the steps. Broken down implementation plan

Installation and Setup

Prerequisites

Node.js 20.19.0 or higher

Install

npm install -g @fission-ai/openspec@latest

Initialize

cd <your-project>
openspec init

Once initialized, it will ask you to select which AI tools you want to set up. OpenSpec supports 28 tools including Claude Code, Cursor, Codex, Copilot and more. Use Space to toggle and Enter to confirm.

After selecting your tools, OpenSpec sets everything up automatically ~ agent skills, slash commands, and config files for each tool you selected.

Once setup is complete, restart your IDE for the slash commands to take effect. Then you are ready to start your first change with /opsx:propose <what-you-want-to-build>

The Four Artifacts

Every change in OpenSpec progresses through four artifacts.

Each artifact builds on the previous one, ensuring implementation starts only after the change is fully understood.

1. Proposal

The Why

The proposal captures the intent behind the change.

Questions answered here:

Why are we doing this?
What problem are we solving?
What value does this provide?

This is where intent gets locked in.

2. Specs

The What

Specs define the requirements and expected behavior.

Questions answered here:

What should happen?
What should the system do?
How should it behave?

These become the source of truth during implementation.

3. Design

The How

Design documents describe the technical approach.

Questions answered here:

Which architecture should we use?
What tradeoffs are involved?
What technical decisions need to be made?

This phase often prevents expensive mistakes before they reach production.

4. Tasks

The Steps

Tasks break the implementation into manageable pieces.

Questions answered here:

What needs to be done?
In what order?
How do we know we're finished?

This becomes the execution plan for both humans and AI agents.

Your First Change

Let's walk through a real example. We are going to add a new User Profile API endpoint using OpenSpec from start to finish.

Step 1: Start the Change

Run the propose command in your AI coding assistant:

/opsx:propose "add-user-profile-api-endpoint"

Your AI will generate all four artifact files automatically:

Created openspec/changes/add-user-profile-api-endpoint/
✓ proposal.md — why we're doing this, what's changing
✓ specs/       — requirements and scenarios
✓ design.md    — technical approach
✓ tasks.md     — implementation checklist
Ready for implementation!

Here is what each artifact looks like:

proposal.md

# Proposal: Add User Profile API Endpoint

## Intent
Users need a way to retrieve and update their profile information
through a dedicated API endpoint.

## Scope
- GET /api/users/:id endpoint
- PUT /api/users/:id endpoint
- Input validation and error handling

## Approach
Use existing REST conventions with JWT authentication middleware.

specs/api/spec.md

# Delta for API

## ADDED Requirements

### Requirement: User Profile Retrieval
The system MUST expose a GET endpoint to retrieve user profile data.

#### Scenario: Fetch profile
- GIVEN an authenticated user
- WHEN GET /api/users/:id is called
- THEN the user profile is returned

design.md

# Design: Add User Profile API Endpoint

## Approach
- Use Express router for route handling
- JWT middleware for authentication
- Joi for input validation
- Return 404 if user not found

tasks.md

# Tasks

## 1. Route Setup
- [ ] 1.1 Create user profile route file
- [ ] 1.2 Register route in main router

## 2. Handlers
- [ ] 2.1 Implement GET /api/users/:id handler
- [ ] 2.2 Implement PUT /api/users/:id handler

## 3. Validation and Error Handling
- [ ] 3.1 Add input validation
- [ ] 3.2 Add error handling middleware

Step 2: Implement

Once you are happy with all the artifacts, run:

/opsx:apply

Your AI now works through the tasks one by one following the spec exactly:

Working through tasks...
✓ 1.1 Created user profile route file
✓ 1.2 Registered route in main router
✓ 2.1 Implemented GET /api/users/:id handler
✓ 2.2 Implemented PUT /api/users/:id handler
✓ 3.1 Added input validation
✓ 3.2 Added error handling middleware
All tasks complete!

No guessing, no assumptions, no scope creep. Your AI follows the spec and nothing else.

Step 3: Archive

Once everything is verified, run:

/opsx:archive

This closes the change completely. It merges your delta specs into the main specs folder and moves the change to the archive permanently.

Archiving add-user-profile-api-endpoint...
✓ Merged specs into openspec/specs/api/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-user-profile-api-endpoint/
Done! Ready for the next feature.

The reasoning behind every decision is now preserved in your repository forever. Next time anyone touches this code ~ including an AI agent ~ the why is already there.

Tips from Real Usage

After using OpenSpec for a few months in fast paced AI driven development, here are a few things I have learned.

Always review the proposal before moving on
The proposal is where intent gets locked in. If something is off there, it carries through to every other artifact. Spend an extra minute here and save yourself a lot of back and forth later.

Be specific with your scope
The more specific you are about what is out of scope, the better your AI performs. Writing "out of scope: custom error pages" is more useful than leaving it vague. AI agents take boundaries seriously when they are written down.

Do not skip the design artifact
It is tempting to jump straight to implementation. But the design phase is where you catch bad technical decisions before they become bad code. Many times the design phase alone has saved me from going down the wrong path.

Use it on existing codebases
OpenSpec is brownfield first. You do not need a fresh project to get value from it. Drop it into an existing codebase and start using it for your next change. The value shows up immediately.

Your specs are living documentation
Every time you archive a change, your specs folder gets more complete. Over time it becomes a genuine source of truth for how your system works and why decisions were made. That is valuable for your whole team, not just for AI agents.

Conclusion

AI coding assistants are powerful. But power without direction is just noise.

OpenSpec is not about slowing down. It is about making sure that when you move fast, you are moving in the right direction. In vibe coding and fast paced AI driven development, the biggest risk is not writing bad code. It is building the wrong thing confidently.

After using OpenSpec for a few months, the biggest shift I noticed was not in the code quality. It was in how much context was being preserved. The why behind decisions no longer lives in chat history or someone's head. It lives in the repository, right next to the code it describes.

If you are doing any kind of AI assisted development and you are not using a spec driven approach, give OpenSpec a try. It takes five minutes to set up and the value shows up on your very first change.

Start with:

/opsx:propose "your-first-change"

And see what happens.

Google Just Made AI Memory Official at Cloud NEXT '26 - And It Made Me Uncomfortable :(

Syed Ibrahim — Sun, 26 Apr 2026 11:39:11 +0000

This is a submission for the Google Cloud NEXT Writing Challenge

I'll be honest. I didn't sit through the full Google Cloud NEXT '26 keynotes. I caught the highlights in between work. That's my level of "following the news."

But one announcement stopped me: Agent Memory Bank, now generally available inside the Gemini Enterprise Agent Platform.

Here's what it does in plain English: your AI agent can now remember things across conversations. Not just inside one session, but across sessions. It dynamically builds memory from past interactions, stores it, and pulls it back when relevant. Using Memory Profiles, agents can recall high-accuracy details with low latency so they don't lose context. (Google Cloud)

Sounds great on paper. But it made me think about something that happened to me recently.

I Already Experienced AI Memory. Without Asking for It.

A few weeks ago I was trying to fix a Decoder init failure on specific Snapdragon/MediaTek chipset phones. It was showing up in Sentry on our Android player SDK, ExoPlayer related. So I was using an AI tool to work through it, asking questions, going back and forth.

At some point I closed that chat and started a completely new one. Different day, different question. But somewhere in that new conversation the AI referenced something specific from the ExoPlayer session. Something I hadn't brought up at all.

So I asked: "are you reading my previous chats?"

It said no.

I gave it the exact context it had referenced. Still denied it.

That's the part that didn't sit right with me. Not that it remembered. That it remembered and then said it didn't. If a system can recall something it claims it cannot access, and then confidently insists otherwise, that's not just a bug. That's a trust problem. Because now I'm sitting there wondering what else it knows that it's not telling me. And the easy fallback is always "AI can make mistakes" which okay, sure, but that line is doing a lot of heavy lifting. It quietly removes accountability. The system moves on. I'm left holding the confusion.

Now Google Is Making Memory an Official Feature

Agent Engine Sessions and Memory Bank, which give agents persistent context across interactions, are now generally available. (The Next Web)

In some ways that's actually more honest. At least now it's documented, intentional, and in an API you can actually inspect.

The idea makes sense for what I build. I work on Django-based AI SaaS. Right now every session resets. Users repeat themselves. Agents forget context. Google showed a demo where a customer moves from text chat to a phone call and the agent seamlessly remembers exactly where they left off. (Google Cloud) That kind of continuity is genuinely useful.

Think of it like a user_preferences table in Django, except Google manages the entire memory layer for you.

But My Trust Questions Remain

If unofficial memory already existed and got denied, what happens with the official version?

What exactly gets stored, and for how long?
Can my users actually delete their memory and trust it's gone?
How do I explain this to users in India who are already cautious about data privacy?
And most practically, where is the clean pip install Django walkthrough?

The codelab demo showed Memory Bank costing less than $5 (Google Codelabs), which is a good sign. But I need to see full production pricing before I build anything serious on top of it.

My Prediction

Persistent agent memory is the right direction. Google's pitch is a unified stack: chips designed for models, models grounded in your data, agents built with those models, all secured by the infrastructure. (Google Cloud) If that holds up, it could genuinely be the default for AI SaaS in 12 months.

But the trust layer has to come with the feature. Users need to know what's remembered, what's stored, and what "delete" actually means.

Google has a real chance to set that standard properly with Agent Memory Bank, especially because the unofficial version already exists and nobody is really talking about it clearly.

Make it transparent, Google. The feature is good. The trust needs to catch up.