vision-driven-design

# Vision Driven Design

<!-- mcp-name: io.github.simonmak-ascent/vision-driven-design -->

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

[![VDD Quality Gates](https://github.com/simonmak-ascent/vision-driven-design/actions/workflows/vdd-quality-gates.yml/badge.svg)](https://github.com/simonmak-ascent/vision-driven-design/actions/workflows/vdd-quality-gates.yml)
[![MCP Tool Definition Quality](https://github.com/simonmak-ascent/vision-driven-design/actions/workflows/tdqs.yml/badge.svg)](https://github.com/simonmak-ascent/vision-driven-design/actions/workflows/tdqs.yml)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.simonmak--ascent%2Fvision--driven--design-4CAF50)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.simonmak-ascent/vision-driven-design)
[![Glama MCP](https://glama.ai/mcp/servers/simonmak-ascent/vision-driven-design/badges/score.svg)](https://glama.ai/mcp/servers/simonmak-ascent/vision-driven-design)
[![Agent Status](https://wdmisgfkoimdpvvduebj.supabase.co/functions/v1/mcp-badge?slug=vdd)](https://agentstatus.dev/mcp-index/vdd)
[![Version](https://img.shields.io/badge/version-1.9.2-blue)](https://github.com/simonmak-ascent/vision-driven-design/releases)
[![MCP tools](https://img.shields.io/badge/MCP-15%20tools-4CAF50)](https://vdd.simonmak.com/api/mcp)
[![API](https://img.shields.io/badge/API-vdd.simonmak.com-006b7d)](https://vdd.simonmak.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Overview

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
```

---

## Table of Contents

- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Commands](#commands)
- [Installation](#installation)
- [MCP API](#mcp-api)
- [Domains Covered](#domains-covered)
- [Best-Practice Benchmark](#best-practice-benchmark)
- [Documentation](#documentation)
- [Repository Structure](#repository-structure)
- [Credits](#credits)
- [License](#license)

---

## Quick Start

```bash
# One-line install
curl -sSL https://raw.githubusercontent.com/simonmak-ascent/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 →](vdd/docs/tutorial.md)** — 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:
```
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/simonmak-ascent/vision-driven-design.git \
  ~/.config/opencode/skills/vision-driven-design/

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

# Cursor
git clone https://github.com/simonmak-ascent/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/simonmak-ascent/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 (15)

`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 Prompts (3)

`start_vdd_project` (vision → validated task list), `implement_next_task` (one test-first task with traceability) and `change_requirement` (cascade a change and re-run the gates). Available on the stdio server and the hosted endpoint.

### MCP Registry (Glama)

The server is listed on [Glama](https://glama.ai/mcp/servers/simonmak-ascent/vision-driven-design), which builds it from source and publishes a hosted remote endpoint plus a **Tool Definition Quality Score** and maintenance rating:

<a href="https://glama.ai/mcp/servers/simonmak-ascent/vision-driven-design"><img src="https://glama.ai/mcp/servers/simonmak-ascent/vision-driven-design/badges/card.svg" alt="Glama quality and maintenance score"></a>

Maintainer notes:

- `glama.json` (repo root) is Glama's registry file. Its [schema](https://glama.ai/mcp/schemas/server.json) consumes exactly one field — `maintainers`. Build/transport/description metadata belongs in `package.json` and this README, **not** here; Glama ignores it.
- Glama genera