Your PO Should Own the Spec, Not the Developer — Here's How Status Gates Fix the AI Handoff Problem

#vscode #productivity #ai #webdev

In most AI-assisted workflows, the developer writes the prompt and owns the outcome. The Product Owner writes a Jira ticket, the developer interprets it, feeds it to an AI agent, and 2,000 lines of code appear. Three sprints later, everyone's still arguing about what was actually specified.

The root cause isn't bad developers or bad POs. It's that nobody owns the spec as a living artifact. Jira tickets describe work to do — they die when the sprint ends. Confluence pages describe features that were planned — they go stale the moment someone changes the code. The actual intent lives in chat logs, Slack threads, and someone's memory.

What if your specs lived in Git?

The idea: each product requirement is a Markdown file with YAML frontmatter, stored in your Git repository right next to the code. One file per requirement, organized in a directory tree that mirrors your feature hierarchy. The frontmatter carries metadata — who owns it, when it was last updated, and crucially, its status.

---
id: R-4201
type: requirement
title: "Add to Cart button"
status: approved
owner: sarah
---

When a user clicks "Add to Cart" on a product page...

No external tools. No Confluence sync. No copy-pasting between systems. The spec is a file, reviewed in PRs, versioned in Git, and readable by both humans and AI agents.

I've been building a VS Code extension called SPECLAN that adds a WYSIWYG editor, spec tree view, and AI implementation tooling on top of this approach (full disclosure: I'm the creator). But the core concept — specs as files with status gates — works with any editor and zero tooling.

Here's the part that changes everything: the status field isn't just a label. It's an ownership protocol.

The status lifecycle

draft → review → approved → in-development → under-test → released

Each transition is a handoff between roles — not a Slack message, not a status change in a project management tool, but a field in the file itself, committed to Git, visible to the entire team.

Here's the key insight: the status isn't a label. It's an ownership signal.

draft means the PO is still thinking. Devs can see it but shouldn't implement it yet.
review means the PO wants the team's eyes on it.
approved means it's been reviewed and is ready to implement — the handoff moment.
in-development means the dev team (or AI agent) owns it now.
under-test means responsibility flows back to the PO — did the result match the intent?
released means everyone agrees it's done. The spec stays as a permanent record.

Walking through it: adding a shopping cart

Sarah the PO creates three Requirements in her spec tree: "Add to Cart" button, cart page with quantity editing, and cart persistence across sessions. She writes each one describing what the feature does, not how to build it. She adds Acceptance Criteria — toast notification within 500ms, cart icon updates without reload, duplicate items increment quantity.

Status: draft. The dev team can see the specs in their tree view, but the status fence prevents premature implementation. Sarah is still thinking.

She moves to review. Marco (senior dev) flags a concern — localStorage has a 5MB limit that could bite them with large carts. Sarah updates the spec. Lisa (QA) adds a missing edge case: what happens at maximum stock quantity? Sarah adds it. All of this happens in Git commits, not Jira comments.

Status moves to approved. Now the dev team takes over. The AI agent reads the approved specs directly — not from a copy-pasted prompt, but through structured tools that give it access to the full requirement text, acceptance criteria, and the spec hierarchy. It implements what was specified, not what it guesses.

After implementation, the status moves to under-test. This is the handback moment — responsibility flows back from the dev team to the PO. Sarah tests each acceptance criterion against the running system. The person who defined the requirement is the person who accepts the result.

Status: released. The spec stays in the repo as the permanent record of what the product does. Six months later, when someone asks "why does the cart sync to the server?", the answer is in the spec file — including Marco's review comment about the 5MB limit.

Why this matters more than you think

It's not just about teams

If you're a solo developer, you're already playing all these roles — you just switch between them unconsciously. You're the PO when you decide what to build. The developer when you implement. The QA when you test.

The problem is these mental switches happen mid-sentence. You're halfway through writing a spec when you think "I know how to build this" and jump straight to coding. The spec never gets finished. Two weeks later, you can't remember what you intended.

Status gates give solo developers forced phase separation:

Specificator hat — write specs, think through edge cases. No coding yet.
Implementor hat — code from the approved spec, not from memory.
Verifier hat — check your own acceptance criteria. "Did I build what I intended?"

Specs outlive sprints

This is the real differentiator from Jira. Tickets describe work. Specs describe the product.

Aspect	Jira Ticket	Spec-as-file
Describes	Work to do	Product behavior
Lifespan	One sprint	Product lifetime
Lives in	External tool	Git, next to the code
After completion	Closed, archived	Still authoritative
AI-readable	Copy-paste into prompt	Structured tools read directly

You can use both — Jira for sprint planning, spec files for the actual requirements. But the spec should outlive the sprint.

AI agents need governance, not freedom

The AI agent reads specs through structured tools, not ad-hoc prompts. It only implements approved specs. It updates the status as work progresses. The human governance layer stays intact even when the coding is automated.

This is the part most AI coding workflows get wrong. They give the AI maximum freedom and wonder why month 3 is a mess. The fix isn't more prompting. It's giving the AI a spec to follow and a lifecycle to respect.

Try it yourself

The Markdown + YAML frontmatter approach works without any tooling — it's just files in Git. But if you want the tree view, WYSIWYG editor, and AI implementation assistant on top of it: