Giving Specs Their Own Home: Why We Built mdspec

Mohammed Zameer — Sat, 14 Mar 2026 05:14:28 +0000

In modern software development, our repositories are suffocating. While Git is the undisputed king of versioning code, it wasn't built for the "messy middle" of thinking. As I started building with AI agents in VS Code, Cursor, and Antigravity, one thing became clear: our current workflow for engineering specs is broken. Our repos are drowning in WIP clutter, our project histories are noisier than ever, and specs—which are now critical infrastructure for AI-driven development—are often duplicated, scattered, and lost. I built mdspec to remove this "Repository Pressure" and give our specs their own home.

The Problem: Repository Pressure

Every developer has felt it: that hesitation before committing a half-baked idea. It’s the visual noise of 500-line Markdown files cluttering your docs/ folder, and the pain of cross-team coordination when a spec lives in a repository half the stakeholders can't access. When specs live strictly inside your repo, they create a bottleneck:

WIP Clutter: Your Git history gets littered with "draft" commits that add no value to the code.
Fragmentation: Discussions across teams become long, disconnected, and hard to track.
Reuse Friction: Specs are often duplicated across features or projects without tedious copy-pasting.

Most importantly, repository pressure steals our freedom to explore. It forces us to be "done" before we've even started. By moving specs to a parallel platform, we unlock the ability for both developers and AI agents to explore alternative scenarios, perform deep codebase analysis, and even prototype new tooling out of existing logic—all without the drag of repository constraints. Whether you're using an AI agent within your IDE for complex system work or manually mapping out a new architectural path, mdspec gives you the space to be messy and analytical until you're right.

Enter mdspec: A Parallel Universe for Your Specs

mdspec is a specification management platform designed for AI-driven development. It is built to work in parallel with Git, not replace it. It gives you a space to think, explore, and iterate on Markdown specs without the weight of the repository.

1. Clean Repos, Clear Minds

We know specs grow exponentially. With mdspec, you can reduce repository clutter by moving your md files out of the code and onto the platform. Your repository stays lean. When you need a spec for reference or context, you pull it via the CLI. When you're done, it’s back in its home.

2. Durable Context for AI Agents

AI agents perform best when they have a stable, structured "source of truth." mdspec centralizes your specs into a durable infrastructure that agents can query directly, providing the context they need to build correctly without hunting through unrelated code.

3. Section-Level Clarity

To solve the problem of fragmented discussions, mdspec introduces Section-Level Comments. Anchor your discussions, @mentions, and resolution tracking to specific sections of your spec. When feedback is anchored to the content, teams move faster without losing alignment.

4. Version Control Independence

One of the core strengths of mdspec is the ability to go cross-team without version control dependence. You can link and share specs across independent repositories—no monorepo required, no copy-pasting needed. Whether it's syncing API docs between Frontend and Backend or coordination with Compliance and Security, mdspec keeps everyone in sync regardless of their repo structure.

5. Native Developer Experience

We didn't want to build "another web tool" that takes you away from your editor. mdspec is built for the terminal and the IDE:

VS Code Extension: Edit and sync specs directly from your workspace.
Robust CLI: Integrate mdspec into your CI/CD pipelines or agentic automation.

The Documentation Lifecycle

Documentation is a living thing that evolves at a different pace than your code. By treating specs as first-class citizens and giving them their own home, mdspec lets you manage that lifecycle with the same precision you apply to your software.

Stop committing doc noise. Give your specs a home.

visit mdspec.dev

Why AI Agents Need Specs: The Birth of MDSpec

Mohammed Zameer — Sat, 28 Feb 2026 23:33:20 +0000

mdspec is an open source spec management platform.

And a spec is a md (markdown) file within your projects.

As we are building with AI agents either via Cursor, VScode or Antigravity, we can see md files or specs (software term for md files) are fast becoming AI infrastructure. A communication layer.

I have used specs mainly for,

Developing spec for a new feature or a bug, generally a new development artifact and discuss the specs with the technical teams. AI agents are good at exploring the features in technical depth, costs, security aspects etc. that can be in one document or more. If there are changes, we can ask the AI agents to change them.
If we need an analysis from a codebase that we need like a compliance analysis on a certain part. Spec that is filtered for the understanding of the target audience or a tool. I have built cost simulation tools based on the codebase, where I built yaml based infrastructure specs that fed into simulation tool. Beauty of these solutions are, the target audience doesn’t need access to whole codebase.   I think spec driven engineering is enabled only by AI agentic era. It was there before but it was time consuming and not scalable.  In essence,
Specs give AI agents the context they need to build correctly.
They also give teams clarity into why and how something was implemented.
Specs are filtered to provide as inputs to other tools or analysis

But AI agentic development is really fast. As with all fast things, we could see two problems were emerging:

Discussions across teams became long and fragmented. Compliance needs those specs. Design needs those specs. Risk Modeling needs those specs.
Specs were duplicated, scattered, and hard to reuse across projects.

I built mdspec to remove that friction. I made it open source to make sure anyone can bend it any way they see fit for their own use cases.

mdspec is a specification management platform designed for fast phased AI-driven development. It helps you:

Create structured, reusable specs
Link specs across features and projects
Maintain clarity as development speed increases
Give AI agents reliable, durable context
When specs become first-class citizens, teams move faster, without losing alignment.
Go cross team securely.

Forem: Mohammed Zameer