VR-SDD: The Agile Developer Level-Up Beyond Vibe Coding and Markdown Islands

TL;DR: Specs + contracts + tests can all be green and yet the product behaviour is still off from what customers expected. The fix is to pin the entire SpecFact + OpenSpec chain to explicit, traceable persona outcomes — not the other way around. That's Value- & Requirements-Driven Spec-Driven Development (VR-SDD): a six-step loop that turns vague backlog prose and disconnected AI prompts into a single source of truth from outcome to code to docs.

The Problem Nobody Talks About: Green Specs, Wrong Product

Every team that adopts Spec-Driven Development eventually runs into a quiet failure mode: all the specs pass, the contracts are green, CI is happy — and the product still doesn't do what users need.

This happens because SDD, like TDD before it, is primarily a correctness mechanism, not a value mechanism. It answers "did we build the thing right?" but not "did we build the right thing." Both questions matter, but only one of them faces the customer.

The same failure mode shows up in three familiar patterns:

• Vibe-coded AI prompts — developers paste a GitHub issue title into Copilot or Cursor, get plausible-looking code, ship it, and discover three sprints later that it solved the wrong interpretation of the feature.
• Markdown island drift — specs live in one tool, acceptance criteria in another, contracts in the repo, and architecture diagrams somewhere else. None of them agree with each other or with the running code.
• Spec-first without grounding — OpenSpec change proposals are well-structured but never traced back to an actual user outcome, so "spec coverage" becomes a vanity metric that obscures whether value was actually delivered.

The root cause in all three cases is the same: there is no explicit, versioned layer of stakeholder outcomes sitting above the spec. The spec is treated as the top of the stack when it should be a derived, constrained implementation of something more important.

What VR-SDD Actually Means

Value- & Requirements-Driven Spec-Driven Development (VR-SDD) is the composition of two well-understood disciplines layered on top of SDD:

• Value-Driven Development — customer value is the primary measure of success, above plan conformance or spec coverage. Work is prioritized and sliced to maximize early, continuous value delivery.
• Requirements-Driven Development (RDD) — every design, implementation, and test artifact is driven by clearly defined business and technical requirements, with end-to-end traceability back to those requirements.

Together they change where the stack starts. Instead of:

Spec → Contracts → Tests → Code → Validation

The full VR-SDD stack becomes:

Persona outcomes → Refined features → Decomposed requirements / stories
  → OpenSpec change proposals (SDD)
    → Contracts & tests (TDD)
      → Code → Validation → Docs

SDD is no longer the top of the chain. It is the engineering implementation layer of a higher-order value and requirements model. The spec justifies itself against that model; it does not replace it.

The 6-Step Loop in Practice

Here is what VR-SDD looks like as a day-in-the-life workflow for an agile team already using SpecFact CLI and OpenSpec.

Step 1 — Define persona-based outcomes in the backlog

Before anything is refined or estimated, anchor each feature to a persona expectation: who needs this, what outcome they need, and how you'll recognize value was delivered. This is the requirements layer — rough and qualitative is fine, but it must exist and be versioned.

In SpecFact, this is where business value enters the daily loop. The standup command surfaces blockers and ordering so the team continuously asks: "are we working on what matters most?"

# Standup with blockers surfaced first
specfact backlog ceremony standup github --blockers-first

# Refinement with DoR check to surface ambiguous items early
specfact backlog ceremony refinement github \
  --framework scrum \
  --persona product-owner

Step 2 — Refine the feature to unambiguity

A rough persona outcome is not a buildable thing. AI-assisted backlog refinement uses templates and Definition of Ready (DoR) enforcement to standardize the feature — title, body, acceptance criteria — before it enters a sprint. SpecFact's policy engine can block items that fail DoR automatically.

# Refine GitHub issues with DoR validation
specfact backlog refine github \
  --repo-owner "your-org" \
  --repo-name "your-repo" \
  --labels feature \
  --framework scrum \
  --persona product-owner \
  --check-dor \
  --write \
  --auto-accept-high-confidence

# Validate policy gates (DoR / DoD / flow)
specfact policy check --scope backlog --bundle current-sprint

The key principle: the CLI should tell you "this story is not ready" before a single line of spec or code is written. Catching ambiguity at the backlog level is an order of magnitude cheaper than catching it in a code review or, worse, in production.

Step 3 — Decompose into meaningful user stories

Break the refined feature into stories that still trace back to the original persona outcome. This is where requirements decomposition happens — each story should be answerable with "did we move the needle for this persona?" not just "did the tests pass?"

SpecFact's dependency analysis keeps track of story-to-story and feature-to-feature relationships, so you can see at a glance which stories are blocked, which have cascading risks, and which deliver independent increments of value.

# Analyse dependencies across the current bundle
specfact backlog dependency-analysis --bundle current-sprint

# Export persona-specific story views for architect review
specfact backlog ceremony refinement github \
  --persona architect \
  --export openspec

Step 4 — Derive OpenSpec change proposals (SDD entry point)

Now — and only now — does SDD begin. OpenSpec change proposals are created from the refined stories, with upstream references to the persona outcome and the backlog item that introduced each spec change. For brownfield projects, SpecFact's import from-code command reverse-engineers current behavior into contracts, surfacing conflicts with the intended spec before implementation starts.

# Reverse-engineer existing code into a contract view (read-only)
specfact import from-code my-service --repo .

# Sync backlog items to OpenSpec change proposals
specfact sync bridge \
  --adapter openspec \
  --mode bidirectional \
  --bundle current-sprint \
  --repo-owner "your-org" \
  --repo-name "your-repo"

The dual-stack enrichment pass combines LLM-enriched spec analysis with the backlog context, so each OpenSpec change proposal carries the full chain: "This spec implements value outcome O-123, derived from feature F-45, decomposed into stories S-101 and S-102."

Step 5 — Implement with TDD first, then code, then validation

With specs and contracts in place, the inner development loop becomes straightforward. Developers work in their AI IDE with the spec bundle exported as context — so Copilot and Cursor suggestions are grounded in the same source of truth as the backlog, not in ad-hoc prompt guesswork.

# Run the full contract test suite locally before committing
specfact contract-test-full --bundle current-sprint

# Progressive CI enforcement: start in shadow mode, graduate to enforce
# .github/workflows/specfact-enforce.yml
# preset: shadow → balanced → strict

The progressive enforcement model (shadow → balanced → strict) means teams start by observing contract and spec violations in CI before making them blocking gates. This removes the fear of breaking legacy workflows while building trust in the process.

Step 6 — Generate docs from the same graph

The final step closes the loop. Because the spec bundle already contains the full chain — persona outcomes, refined features, stories, OpenSpec changes, contracts, test results — documentation can be generated as views over that graph rather than as hand-maintained markdown islands.

Architecture wikis, API docs, and behavior summaries all derive from the same source of truth. When the spec changes, the docs update. When a contract drifts, the docs reflect it.

# Export the spec bundle as wiki-ready Markdown
specfact export docs \
  --bundle current-sprint \
  --format markdown \
  --output docs/wiki/

# Generate persona-specific views
specfact export docs \
  --bundle current-sprint \
  --persona product-owner \
  --output docs/po-view/

What Teams Need to Get Used To

Adopting VR-SDD is straightforward in principle but requires three concrete mindset shifts:

1. The spec is downstream, not upstream

The hardest shift for teams already doing SDD is accepting that the spec is a derived artifact, not the primary truth. Persona outcomes and refined requirements sit above it. Code changes without spec changes are still suspect; but spec changes without requirement changes are equally suspect. Both directions of the traceability chain matter.

2. "All green" is necessary but not sufficient

Contract tests passing in CI is the floor, not the ceiling. The real DoD check is: "does this sprint increment actually move a persona outcome?" SpecFact's business value scoring and policy engine provide the tooling to make that visible, but teams have to decide to use them as gates rather than as optional dashboards.

3. The backlog is a CLI concern, not just a web UI concern

Instead of only clicking in GitHub or Jira, teams run specfact backlog refine and specfact sync bridge as part of refinement and sprint planning. The mental model shifts from "the backlog tool is the system of record" to "SpecFact is the orchestrator and canonical transformer; the backlog tools are stores."

How AI-First Developers Grow Into Architecture Roles

There is an interesting side effect of VR-SDD that is easy to overlook: it creates a natural growth path for developers who arrived at software engineering through AI-assisted development.

An AI-first developer who relies on vibe-coded prompts operates at the code level. When they adopt SpecFact + OpenSpec with VR-SDD grounding, they are forced — by the tool — to think at three levels simultaneously:

Every time a developer writes or reviews an OpenSpec change proposal, they are doing light architecture work. Every time they check a DoR validation report, they are doing requirements engineering. The skills build naturally from the workflow, without requiring a formal "become an architect" training track.

The spec bundle also becomes a persistent, searchable record of why decisions were made — the kind of institutional knowledge that normally lives only in the heads of senior engineers or gets lost entirely. AI-first developers who maintain spec bundles are building that knowledge base automatically.

Reducing Mental Load: One Source of Truth

One of the most underrated benefits of VR-SDD is cognitive, not architectural. Right now, a typical agile developer carries context across five or more disconnected tools simultaneously: GitHub Issues, Jira, Confluence, the codebase, Slack threads about the feature, and whatever AI chat session generated the last draft. None of these agree. All of them drift.

SpecFact's bridge adapters and bidirectional sync collapse this into a single project bundle. The backlog, the spec, the contracts, and the test results are all co-located and versioned together. When you open a standup or a sprint review, SpecFact can tell you — from the same bundle — which stories are drifting, which contracts are violated, which backlog items are missing DoR, and which value scores are not moving.

That is not just productivity. That is the difference between a developer who is always partially confused and one who always has grounded context.

Where This Is Heading

SpecFact CLI v0.38+ is actively building out the module system and marketplace that will make VR-SDD fully first-class. Upcoming work includes:

• Value/requirements layer in the bundle — a formal schema for persona outcomes, value metrics, and requirement records that feed the OpenSpec change proposal creation process.
• Upward traceability commands — CLI queries that answer "show me which specs, contracts, and test results implement requirement R-123 and whether we have evidence that R-123 was actually met."
• Doc generation from the spec graph — first-class specfact export docs that produces ADRs, API docs, and wiki views from the living spec bundle rather than hand-maintained markdown.
• Sidecar validation — zero-code-modification contract enforcement for legacy modules where adding decorators isn't feasible.

The direction is clear: SpecFact keeps moving up the stack, from code-level enforcement toward full-lifecycle traceability that starts with a persona expectation and ends with validated, documented evidence that the expectation was met.

Getting Started Today

You don't need to implement the full VR-SDD stack from day one. The practical entry point is the same as always — start with what you have and add layers progressively:

# Install / upgrade
pip install specfact-cli
# or
uvx specfact-cli@latest --version

# Start with a read-only analysis
specfact init --ide cursor
specfact import from-code my-project --repo .
specfact plan review my-project

Conclusion

The agile developer flow doesn't need more tools. It needs fewer, better-connected layers — with a clear chain from "what the user actually needs" down to "what the code actually does."

VR-SDD is that chain. SpecFact + OpenSpec are the tooling that makes it tractable in a real repo and a real CI pipeline. And the developers who adopt it early are the ones who, six months from now, have built the architectural instincts that AI-generated code alone cannot provide.

Stop wrestling markdown artifacts and misaligned prompts. Start from outcomes. Let the spec be derived. Keep the contracts honest.

Further Reading

• AI-Assisted Backlog Refinement: Empowering DevOps and Agile Teams
• From Vibe Coding to Verified Specs: How SpecFact Completes the SDD Workflow
• DevOps Backlog Sync Capabilities
• SpecFact CLI on GitHub
• OpenSpec
• SpecFact Docs