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.
Top comments (0)