What spec-driven development is
Spec-driven development (SDD) treats a written specification as the source of truth for what to build. Code is a consequence of that spec — not the other way around, and not a transcript of the last chat turn.
A useful spec answers *what* and *why* before *how*. It names users, flows, constraints, and acceptance. The implementation plan then maps those needs onto packages, screens, and tasks. Reviewers can reject a pull request that satisfies the code but violates the spec.
- Constitution — standing principles that do not change every feature (stack, platforms, privacy).
- Specification — the product for this increment: users, journeys, edge cases.
- Plan — the smallest stack and screen recipes that can deliver that spec.
- Tasks — dependency-ordered work the implementer (human or agent) can execute.
- Analysis — a consistency check before anyone writes production code.
How it differs from prompt-driven coding
| Prompt-driven | Spec-driven | |
|---|---|---|
| Source of truth | The latest message | Checked-in spec + constitution |
| Stack choices | Whatever the model recalls | Locked by plan and catalog |
| Review | Diff only | Diff against spec, plan, and tasks |
| Handoff | Re-explain the product | Open specs/<nnn>/spec.md |
| Failure mode | Silent drift, extra packages | Inconsistency report, then fix |
Prompt-driven work is fast for a spike. It fails when the agent invents a second UI kit, adds persistence nobody asked for, or forgets an acceptance rule that lived only in turn 14. SDD spends tokens up front so implement stays cheap and checkable.
How Nuvyn applies SDD
Nuvyn is a spec-driven CLI for .NET MAUI apps on Android, iOS, Windows, and Mac Catalyst. nuvyn init creates a new host. nuvyn adopt attaches the slash chain to an existing MAUI app without rewriting it. Domain is yours. A greenfield stack is Nuvyntra: MVVMExpress, Lumina UIKit, HttpForge, and the smallest MauiEssentials plugin set.
/nuvyn.constitution → /nuvyn.specify → /nuvyn.clarify → /nuvyn.plan
→ /nuvyn.checklist → /nuvyn.task → /nuvyn.analysis
→ /nuvyn.implement → /nuvyn.convergenuvyn init writes the host and the workflow files. nuvyn adopt writes workflow files only — .nuvyn/, skills, and adopt-report.md. The slash chain then produces the artifacts. Skills are domain-agnostic — retail, field, bank, civic, clinic, or anything else. They lock only the MAUI + Lumina stack on a new host. Standing law lives in .nuvyn/reference/constraints.md so each /nuvyn.* command stays short.
| Command | Writes | Purpose |
|---|---|---|
| /nuvyn.constitution | .nuvyn/constitution.md | Nuvyntra principles plus optional product rules |
| /nuvyn.specify | specs/<nnn>/spec.md | What / why — the mobile product spec |
| /nuvyn.clarify | updates spec.md | Resolve ambiguities with at most five questions |
| /nuvyn.plan | plan.md + research.md | Packages and one Lumina recipe per screen |
| /nuvyn.checklist | checklists/<domain>.md | Optional reviewer quality gate |
| /nuvyn.task | tasks.md | Dependency-ordered tasks (T001 [P] [US1]) |
| /nuvyn.analysis | report only | Spec / plan / tasks consistency |
| /nuvyn.implement | host code | Build the feature on the locked stack |
| /nuvyn.converge | appends tasks.md | Remaining work after implement |
Why a locked stack is part of the spec
A generic spec can still produce a random architecture. Nuvyn treats the ecosystem as constitution: sleek Lumina screens, catalog-first packages, API or in-memory data until you ask to persist. That is still SDD — the spec names the product; the constitution names the non-negotiables.
- Four platforms only. Tizen, Flutter, React Native, WPF, WinUI, Avalonia, and Uno are out of scope.
- No new
Plugin.Maui.*until the user asks./nuvyn.planthen picks the smallest catalog fit. - One Lumina recipe per screen. No raw
Entry/Button/Labelwhen anNV*exists. - An outside library needs a Catalog gap row in
plan.md.
Ready to try it? User guide — install and run the chain