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.

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

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 hosted 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 — 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:

"vdd": {
  "type": "remote",
  "url": "https://vdd.simonmak.com/api/mcp",
  "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/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: