v-model

A Claude Code plugin that runs a coding task through the NASA V-Model: define each level and its verification on the way down, implement at the bottom, then climb back up verifying — and refuse to call it done until the project's real test command passes and every requirement traces to a test that command actually runs. Install it, type /v-model, and describe what you want built.

Contents

• The problem · The solution · Not just planning · Tailoring · Install · Usage · What it produces · The done-gate · How it differs · Limitations

The systems-engineering "Vee" was formalized by Forsberg & Mooz (1991) — who named it the Vee, hence this project's name — and adopted in NASA's Systems Engineering Handbook.

The problem

LLMs build fast but leave you unable to trust the result:

• they make silent assumptions and run with them;
• they claim "done" with no evidence — believable but unverified;
• they produce code you can't trace back to any requirement;
• they collapse a problem's distinct levels into one mushy "plan."

The solution

Bring the discipline of systems engineering to the agent — five guardrails that each target one of those failures:

Discipline	Addresses
Leveled altitude	mushy, collapsed planning
Paired verification on descent	tests written late, or never
Traceability spine	untraceable code, orphan requirements
Delegated done-gate	"believable but unverified" completion claims
Tailoring gate	ceremony on trivial tasks

Not just planning

"Write a spec, build, then test" is already everywhere. The V-Model earns its place with three disciplines planning modes skip:

1. Leveled altitude — ConOps → System Requirements → Subsystem/High-Level Design → Component Detailed Design are distinct levels. The skill won't let you collapse them into one mushy plan.
2. Paired verification, defined on the way down — each level writes its own verification plan at the same altitude and same moment, before descending. You never write a test after the thing it tests.
3. Traceability spine — a matrix maps every requirement to the verification that proves it, and every line of code back to a requirement. Nothing untraced ships; nothing untested ships.

 DESCEND (define + plan verification together)        CLIMB (verify, then validate)
   ConOps            <----- validates ----->            System Validation
   System Reqs       <----- verifies ----->             System Verification
   Subsystem Design  <----- verifies ----->             Subsystem Verification
   Component Design  <----- verifies ----->             Component Verification
                     \                     /
                       IMPLEMENT (bottom of the V)
                     spine: docs/v-model/<slug>/traceability.md

Tailoring (no ceremony on small tasks)

The skill classifies scope first, so it never sledgehammers a one-liner:

• trivial (one-liner, config) → a single traceability file + one test. No ceremony.
• feature → the full single V.
• system → decompose into sub-Vs under one system-level V.

Install

Claude-first. Two ways:

As a plugin (persistent): from within Claude Code, add the marketplace, then install:

/plugin marketplace add omar-A-hassan/vee
/plugin install v-model@v-model-skills

Then /v-model is available in any session. Use /plugin to manage it.

For one session (no install): clone the repo and point Claude Code at it:

git clone https://github.com/omar-A-hassan/vee.git
claude --plugin-dir ./vee

As a personal skill: copy skills/v-model/SKILL.md into your personal skills directory and invoke it with /v-model.

Usage

/v-model add rate limiting to the public API

The skill states its tailoring decision, descends the left side writing the artifacts below, implements, then climbs the right side updating the matrix until every requirement shows a passing verification — and finally applies the done-gate.

See EXAMPLES.md for a full worked run.

What it produces

Per task, under docs/v-model/<slug>/: