Vision Driven Design

From vision to verified impact — an AI-native, fully autonomous software development methodology.

Provide a human vision statement. The AI autonomously researches, audits your codebase, generates specs and plans, implements, and validates — with bi-directional verification at every junction to ensure nothing is missed or invented.

mermaid

graph LR
    V[1. Vision<br/>Human Input] -->|<-->| S[2. Strategy<br/>AI Research]
    S -->|<-->| T[3. Tactics<br/>AI Audit]
    T -->|<-->| SP[4. Specs<br/>SDD]
    SP -->|<-->| PL[5. Plan]
    PL -->|<-->| TK[6. Tasks]
    TK -->|<-->| IM[7. Implement]
    IM -->|<-->| VS[8. Validate<br/>Impact Verified]

    style V fill:#4CAF50,color:#fff
    style S fill:#2196F3,color:#fff
    style T fill:#FF9800,color:#fff
    style SP fill:#9C27B0,color:#fff
    style VS fill:#4CAF50,color:#fff

Quick Start
How It Works
Commands
Installation
MCP API
Domains Covered
Best-Practice Benchmark
Documentation
Repository Structure
Credits
License

Quick Start

bash

# One-line install
curl -sSL https://raw.githubusercontent.com/simonplmak-cloud/vision-driven-design/main/scripts/install.sh | bash

Then in your project:

bash

/vdd:init                          # Generate project constitution
/vdd:vision "your vision here"     # The only human input required

# Or run end-to-end in one command:
/vdd:e2e "your vision here"        # Full chain: init→vision→...→validate

The AI handles the rest — researching, auditing, generating specs, planning, implementing, and validating — with self-gating at 7 bi-directional verification junctions.

Tutorial → — 30-minute walkthrough building a real project.

bash

# Want human gates? Add to constitution.md:
## VDD Mode: gated

How It Works

VDD follows Goldratt's recursive Strategy-Tactic decomposition: every phase is simultaneously the Tactic for its parent and the Strategy for its child.

Phase	S&T Role	Output
0. Constitution	(pre-chain)	`constitution.md` — Immutable project rules
1. Vision	L1 Strategy: What impact?	`vision.md` — Impact model, success metrics
2. Strategy	L1 Tactic → L2 Strategy	`strategy.md` — Research, 12 pillars, risk register
3. Tactics	L2 Tactic → L3 Strategy	`tactics.md` — Codebase audit, 38 action items
4. Specs	L3 Tactic → L4 Strategy	`spec.md` — MoSCoW acceptance criteria
5. Plan	L4 Tactic → L5 Strategy	`plan.md`, `data-model.md`, `contracts/`
6. Tasks	L5 Tactic → L6 Strategy	`tasks.md` — Test-first atomic tasks
7. Implement	L6 Tactic → L7 Strategy	Code — Per-task commits with full traceability
8. Validate	L7 Tactic — Did it work?	`impact-report.md` — Drift + impact verification

7 bi-directional gates verify both directions at every junction (108 total checks). Each gate validates 4 S&T assumptions: Necessity, Achievability, Sufficiency, Warnings.

Every code commit traces back to the original vision statement:

Code

V-001 → S-002 → T-003 → SP-004 → PL-005 → TK-006 → commit

Commands

Command	Phase	Action
`/vdd:init`	0	Generate `constitution.md` from project context
`/vdd:vision "statement"`	1	Expand freeform vision → structured `vision.md`
`/vdd:strategize`	2	Load domain primers, spawn research subagents, synthesize `strategy.md`
`/vdd:tactics`	3	Audit repo → gap analysis → `tactics.md`
`/vdd:specify <ID \| "desc">`	4	Generate `spec.md` (or freeform — skips V/S/T)
`/vdd:clarify <feature>`	4	Clarification pass on a spec
`/vdd:plan <feature>`	5	Generate `plan.md`, `data-model.md`, `contracts/`
`/vdd:tasks <feature>`	6	Generate `tasks.md`
`/vdd:get-next-task <feature>`	7	Extract next uncompleted task
`/vdd:implement <task-id>`	7	Execute single task, verify, commit
`/vdd:validate`	8	Full-chain traceability + drift + impact report
`/vdd:trace`	any	Bidirectional traceability matrix
`/vdd:analyze <feature>`	any	Cross-artifact consistency analysis
`/vdd:amend "what changed"`	any	Cascade requirement change through full chain
`/vdd:detect-environment`	any	Report per-phase tool/MCP requirements + available capabilities
`/vdd:e2e "vision statement"`	0–8	End-to-end: run full 8-phase chain in one call, writes all 10+ template files
`/vdd:e2e -clone <domain>`	7	Clone: crawl site (browserless/fetch) into a full dataset + exact UI/UX + rebuilt backend + generated schema + AI tools + deployable dynamic site (vdd/clone-site/) from a domain (https/http/www/bare)

Installation

bash

# OpenCode
git clone https://github.com/simonplmak-cloud/vision-driven-design.git \
  ~/.config/opencode/skills/vision-driven-design/

# Claude Code
git clone https://github.com/simonplmak-cloud/vision-driven-design.git \
  ~/.claude/skills/vision-driven-design/

# Cursor
git clone https://github.com/simonplmak-cloud/vision-driven-design.git \
  .cursor/skills/vision-driven-design/

Local MCP (from source)

To run the MCP server locally (stdio) instead of the hosted endpoint:

bash

# 1. Clone the repo
git clone https://github.com/simonplmak-cloud/vision-driven-design.git

# 2. Install deps + build the TypeScript packages
cd vision-driven-design
pnpm install
pnpm -r build

# 3. Point your agent at the built stdio entry point

OpenCode (opencode.json):

json

"vdd": {
  "type": "local",
  "command": ["node", "<repo>/packages/vdd-mcp/dist/stdio.js"],
  "enabled": true
}

Claude Desktop (claude_desktop_config.json):

json

"vdd": {
  "command": "node",
  "args": ["<repo>/packages/vdd-mcp/dist/stdio.js"],
  "type": "stdio"
}

MCP API

VDD is available as a public MCP server at https://vdd.simonmak.com — 15 tools, no API key required — over the MCP Streamable HTTP transport at https://vdd.simonmak.com/api/mcp (also reachable at /mcp). The legacy SSE endpoint is retired: https://vdd.simonmak.com/api/sse now returns an HTTP 308 redirect to /api/mcp.

Agent Configuration

OpenCode — add to opencode.json:

json

"vdd": {
  "type": "remote",
  "url": "https://vdd.simonmak.com/api/mcp",
  "timeout": 120000
}

Claude Desktop — add to claude_desktop_config.json:

json

"vdd": {
  "command": "npx",
  "args": ["-y", "@simonmak-ascent/mcp"],
  "type": "stdio"
}

Cursor — add MCP server URL: https://vdd.simonmak.com/api/mcp

Any Streamable HTTP client (Smithery, Claude Code, …) — MCP server URL: https://vdd.simonmak.com/api/mcp

MCP Tools (16)

vdd_init, vdd_vision, vdd_strategize, vdd_tactics, vdd_specify, vdd_clarify, vdd_plan, vdd_tasks, vdd_get_next_task, vdd_implement, vdd_validate, vdd_inspect, vdd_amend, vdd_clone, vdd_detect_environment.

The one-call e2e shortcut is not an MCP tool (it duplicates the phase sequence); use the CLI vdd e2e "vision" instead.

All tools accept: statement, projectRoot, actionItemId, feature, taskId, description, availableTools, capabilities, researchFindings, artifactFiles.

MCP Registry (Glama)

The server is listed on Glama, which builds it from source and publishes a hosted remote endpoint plus a Tool Definition Quality Score and maintenance rating:

Maintainer notes:

glama.json (repo root) is Glama's registry file. Its schema consumes exactly one field — maintainers. Build/transport/description metadata belongs in package.json and this README, not here; Glama ignores it.
Glama generates its own container build from the stdio entrypoint (packages/vdd-mcp/dist/stdio.js), wrapped with mcp-proxy. The root Dockerfile is for self-hosting the Streamable HTTP server, not for Glama.
After tool-definition changes: sync the repository and run Build & Release in the Glama admin. Tool-level scores refresh on the next sweep; the server-level coherence score re-runs less often.
Also published to the Official MCP Registry as io.github.simonplmak-cloud/vision-driven-design (manifest: server.json) — PulseMCP and other directories ingest from there.
Listed in the awesome-mcp-servers community list under Developer Tools.
Listed on Agent Status — an outside-in MCP reliability index that probes reach, catalog, and tool calls from real hosts (Cursor, Claude, VS Code, ChatGPT). The submission created the Free dashboard account; the score populates after the first probe.

API Reference

Method	Description
POST `/api/mcp`	Streamable HTTP — JSON-RPC `initialize`, `tools/list`, `tools/call` (stateless)
GET `/api/mcp`	HTML docs page for browsers; 405 for MCP clients (no server-initiated stream)
DELETE `/api/mcp`	204 — no session state to terminate
`/api/sse`	Retired — HTTP 308 redirect to `/api/mcp`

bash

# Streamable HTTP call example
curl -X POST https://vdd.simonmak.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

bash

# tools/call example
curl -X POST https://vdd.simonmak.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"vdd_validate","arguments":{"projectRoot":"."}},"id":1}'

The full TypeScript engine (packages/vdd-engine, packages/vdd-mcp, packages/vdd-cli) is included in this repo.

Domains Covered

VDD loads domain-specific research patterns during the Strategy phase based on your vision:

Domain	What it covers
WebApp	UX, accessibility (WCAG 2.2), performance budgets, framework evaluation
Data Storage	Schema design, indexing strategy, data governance, ACID vs eventual
ETL	Pipeline architecture, data quality, batch vs streaming
Infrastructure	CI/CD, observability, security, scaling, disaster recovery
Human Factors	Behavioral economics, cognitive load, habit formation, accessibility cognition
Verification Toolchain	Playwright, Browserless, Sentry, CI/CD quality pipeline
Safety-Critical	FMEA/FTA, DO-178C/IEC 62304 safety integrity levels

human-factors.md and verification-toolchain.md are loaded unconditionally for every project.

Best-Practice Benchmark

VDD is benchmarked against NASA SE, CMMI REQM, DO-178C, IEC 62304, DORA, ISO 29148, and GitHub Spec Kit:

47/47 criteria matched (100%), 11 exceeded, 0 gaps.

Full benchmark matrix → | Compliance evidence templates →

Documentation

File	Contents
`SKILL.md`	Full command reference and workflow
`vdd/docs/tutorial.md`	30-minute walkthrough
`vdd/docs/comparison.md`	VDD vs SDD vs vibe coding vs TDD
`vdd/docs/best-practice-benchmark.md`	Standards alignment matrix
`references/workflow-phases.md`	Step-by-step phase instructions (authoritative)
`references/artifact-templates.md`	Copy-paste templates for all 11 artifacts
`references/quality-gates.md`	7 gates with 108 checks + CI/CD
`references/anti-patterns.md`	24 failure modes and fixes
`references/compliance-evidence.md`	DO-178C/IEC 62304/CMMI/ISO 29148 evidence maps
`references/clone-workflow.md`	Website cloning — crawl → dataset → deployable dynamic site
`references/quick-reference.md`	One-page cheat sheet

Repository Structure

Code

├── SKILL.md                         # Entry point — loaded by OpenCode
├── README.md                        # This file
├── AGENTS.md                        # Instructions for AI agents
├── constitution.md                  # Project constitution (dogfooded)
├── CHANGELOG.md                     # Versioned change history
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE.md                       # MIT
├── index.html                       # GitHub Pages landing page
├── pnpm-workspace.yaml              # Workspace config
├── package.json                     # Root package (Vercel + workspace)
├── vercel.json                      # Vercel deployment config
├── Dockerfile                       # Self-host build — Streamable HTTP MCP server
├── glama.json                       # Glama registry file (maintainers only)
├── server.json                      # Official MCP Registry manifest
├── domain-primers/                  # 7 domain research patterns
│   ├── webapp.md
│   ├── data-storage.md
│   ├── etl.md
│   ├── infrastructure.md
│   ├── human-factors.md             # Loaded unconditionally
│   ├── verification-toolchain.md    # Loaded unconditionally
│   └── safety-critical.md           # FMEA/FTA, DO-178C/IEC 62304
├── references/                      # 10 authoritative reference docs
│   ├── INDEX.md                     # Navigation map
│   ├── quick-reference.md           # 1-page cheat sheet
│   ├── workflow-phases.md           # Phase order (authoritative)
│   ├── artifact-templates.md        # 11 artifact templates (authoritative)
│   ├── prompt-patterns.md           # AI prompts (authoritative)
│   ├── quality-gates.md             # 7 gates + 108 checks (authoritative)
│   ├── ai-agent-patterns.md         # Agent orchestration (authoritative)
│   ├── anti-patterns.md             # 24 failure modes (authoritative)
│   ├── traceability-matrix.md       # RTM format + CI/CD
│   └── compliance-evidence.md       # Evidence maps
├── vdd/                             # VDD chain artifacts
│   ├── vision.md                    # Vision, impact model, 17 impacts
│   ├── strategy.md                  # 12 strategic pillars
│   ├── tactics.md                   # 38 action items (all DONE)
│   ├── impact-report.md             # Full-chain traceability + drift
│   ├── docs/                        # 16 guides and references
│   └── specs/                       # 3 feature specs
├── packages/                        # TypeScript monorepo
│   ├── vdd-engine/                  # Shared core — 18 phase functions + meta.ts
│   ├── vdd-mcp/                     # MCP server — 15 tools, stdio + Streamable HTTP
│   └── vdd-cli/                     # CLI binary — 17 subcommands
├── api/                             # Vercel MCP endpoint
│   ├── mcp.js                       # Streamable HTTP MCP endpoint (15 tools)
│   └── _vdd-rpc.js                  # Shared JSON-RPC core + browser docs page (not routed)
├── scripts/                         # 4 installer/helper scripts
└── .github/                         # GitHub config
    ├── CODEOWNERS
    ├── ISSUE_TEMPLATE/
    └── workflows/

Credits

Built on:

Goldratt's Strategy-and-Tactic Tree — recursive decomposition at every phase
Impact Mapping (Gojko Adzic) — goal → actors → impacts → deliverables
GitHub Spec Kit — spec-driven development with AI agents
NASA Systems Engineering — bidirectional traceability and verification chains
CMMI Requirements Management — bidirectional traceability of requirements

License

MIT — see LICENSE.md

Vision Driven Design README

Vision Driven Design

Table of Contents

Quick Start

How It Works

Commands

Installation

Local MCP (from source)

MCP API

Agent Configuration

MCP Tools (16)

MCP Registry (Glama)

API Reference

Domains Covered

Best-Practice Benchmark

Documentation

Repository Structure

Credits

License