Planning used to be visual. Then AI turned it into a wall of text.

Introduction

I'm a product manager. My job has always been to write down what should be built and get people to agree on it. For most of that time the tools were visual — whiteboards, sticky notes, story maps. You could stand in front of a plan and see the shape of it.

Spec-driven development changed the stakes. The spec used to be the starting point for a conversation with engineers. Now it's the input to a machine that builds exactly what it reads. Vague spec, wrong product, at speed.

So specs got longer. Much longer. And they moved into markdown files, because that's what agents read.

I built Sutra because a spec detailed enough for an AI agent is a document no human wants to read.

The Problem

Spec-driven development asks you to write instructions precise enough for an agent to execute. That means edge cases, data shapes, error states, acceptance criteria, scope boundaries. All of it, written out.

Then you put it in a markdown file, and you have a wall of text.

• Writing is hard. You're holding the whole system in your head while typing linearly. There's no structure to hang the detail on, so detail goes wherever you happen to be in the document.
• Reviewing is harder. Nobody reads two thousand lines of markdown carefully. Your tech lead skims it. Your compliance reviewer skims it. Everyone approves. Nobody has actually read the requirement that will cause the problem.
• Collaboration barely happens. You can't point at a paragraph. You can't tell what's settled and what's still open. Feedback arrives as comments in a doc, decisions get made in a chat thread, and the spec quietly stops matching what everyone believes.
• Nothing tells you what's missing. A wall of text looks complete because it's long. Length is not coverage.

The irony is that the spec is now the most important artifact in the project, and it's in the least usable format we have.

The Solution

Sutra puts the plan back where people can see it.

You work in visual story maps: Epic → Flow → Story. The epic is the intent. The flow is the path a user takes. The story is the unit an agent can actually build against. Underneath, it's still a spec precise enough for an agent to execute — you just aren't the one reading it in raw form.

That fixes the three problems at once. You write into a frame instead of a blank page, so detail lands where it belongs. Reviewers take one flow at a time and can see what they've covered. And because each piece is addressable, a conversation about a requirement can be about that requirement.

Then Sutra does the part a markdown file never could. It reads what you've written and tells you what you left unstated — the assumptions an agent would otherwise fill in silently. You resolve them before any code exists.

Same detail. Visual instead of linear.

Key Features

• Visual story maps — Epic → Flow → Story. Every requirement has a location and a scope. Reviewers work through a map, not a scroll bar. The agent still gets a clean spec.
• Assumption auditing — Sutra interrogates the spec while you write it and flags the gaps an agent would guess its way through. A gap caught in a story costs a sentence. The same gap caught after generation costs a sprint.
• Decision matrix — A running log of what got decided. Yours and the AI's, side by side. The second category is the one that matters: the assumptions you accepted by not objecting.
• Security validation — Run it at plan time, before there's code to scan. Holes found in a story are cheap. The same holes found in a pen test are not.
• Drift detection — Compare what was built against what was specified. Sutra flags full and partial drift, explains its reasoning, and records how you resolved it.
• Brownfield scanning — Point Sutra at an existing repo and it reconstructs the spec structure from what's already there. You don't need a greenfield project to start.
• Bring your own key — Your API key, your model, your data.

Frequently Asked Questions

What problem does Sutra solve?

Specs written for AI agents have to be detailed, and detailed markdown is unreadable. Sutra makes that detail structured, so it can actually be written, reviewed, and agreed on before it goes to an agent.

Who should use Sutra?

Product managers writing specs for AI-assisted teams, and the people who have to review those specs — tech leads, architects, compliance owners. It's built for teams where more than one person has to agree on what's being built.

When is Sutra the right choice?

When your spec has outgrown a document. If you're prompting an agent for a weekend project, a markdown file is fine. If your spec is long enough that reviewers skim it, you've already lost the review, and structure is the fix.

How is Sutra different from alternatives?

Most tools in this space generate. Give them a prompt, get a spec or an app. They optimize for getting to code fast.

Sutra doesn't generate your application. It's the layer where the spec gets written, reviewed, and held to. Generators make promises. Governors keep receipts.

Conclusion

Spec-driven development put the spec at the center of the process. The tooling never caught up. We're writing the most important artifact in the project in the same format we use for READMEs, and then wondering why nobody reads it.

Sutra is live at sutrasdd.app. The free tier is enough to write a real spec and give to your Ai agents.