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.

---

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

---

Table of Contents

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

---

Quick Start

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

Then in your project:

/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.

# 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:

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

# 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 public SSE endpoint:

# 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):

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

Claude Desktop (claude_desktop_config.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/api/sse. 16 tools, SSE transport with JSON-RPC 2.0, no API key required.

Agent Configuration

OpenCode — add to opencode.json:

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

Claude Desktop — add to claude_desktop_config.json:

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

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

Any SSE-compatible agent — endpoint: https://vdd.simonmak.com/api/sse

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_trace, vdd_analyze, 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.

API Reference

Method	Description
GET /api/sse	SSE stream (MCP client) or HTML docs (browser)
POST /api/sse	JSON-RPC — initialize, tools/list, tools/call

# JSON-RPC call example
curl -X POST https://vdd.simonmak.com/api/sse \
  -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

├── 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)
├── 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 — 17 phase functions + meta.ts
│   ├── vdd-mcp/                     # MCP server — 16 tools, stdio + Streamable HTTP
│   └── vdd-cli/                     # CLI binary — 17 subcommands
├── api/                             # Vercel MCP endpoint
│   └── sse.js                       # MCP SSE + JSON-RPC 2.0 handler
├── 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