visionspec

VisionSpec

Multi-domain specification orchestration for humans and AI agents.

Overview

VisionSpec bridges the gap between organizational intent and executable specifications for AI coding agents. It implements Amazon's Working Backwards methodology to ensure every requirement traces back to a specific customer outcome.

Key Capabilities:

• 📣 Working Backwards flow - Start with vision (Press Release), derive requirements (PRD)
• 🎯 Dual-methodology system - Separate requirements (WHAT) from implementation (HOW) methodologies
• 🔄 AIDLC workflow - Full AWS AI-DLC integration with 12 document types across 3 phases
• 📋 V2MOM strategic planning - Company, department, and team-level strategic alignment
• ✍️ Domain-specific authoring - Separate specs for PM, UX, Engineering
• ⚙️ LLM synthesis - Generate Press, FAQ, PRD, TRD, TPD, IRD from source specs
• 📊 Structured evaluation - Per-domain LLM judges with 1-5 numeric scoring
• 🔄 Reconciliation - Conflict detection and tradeoff resolution
• 📦 Target adapters - Export to SpecKit, GSD, GasTown, GasCity, AWS AI-DLC, OpenSpec

All synthesized documents are committed to git and can be reviewed, edited, and refined by humans or collaboratively with AI assistants.

Installation

go install github.com/ProductBuildersHQ/visionspec/cmd/visionspec@v0.13.0

Quick Start

# Initialize a new project
visionspec init user-onboarding

# Or with a specific workflow methodology
visionspec init user-onboarding --workflow=aws-working-backwards/product

# Validate project structure
visionspec lint

# Check project status
visionspec status
visionspec status --format json
visionspec status --format html > status.html

Spec-Workflows Integration

VisionSpec can load workflows, templates, and rubrics from external spec-workflows repositories. This enables organizations to fork and customize methodologies.

# Clone spec-workflows (auto-discovered from ~/.config/visionspec/)
git clone https://github.com/ProductBuildersHQ/spec-workflows ~/.config/visionspec/spec-workflows

# List available workflows
visionspec workflows

# Initialize with a specific methodology
visionspec init my-product --workflow=aws-working-backwards/product
visionspec init my-feature --workflow=lean-startup/feature

Auto-discovery searches: --workflows-repo flag → VISIONSPEC_WORKFLOWS_REPO env → upward directory walk → ~/.config/visionspec/spec-workflows/

Directory Structure

docs/specs/
├── CONSTITUTION.md                    # Repo-level governance
├── ROADMAP.md                         # Cross-project priorities
└── {project}/                         # kebab-case project name
    ├── source/                        # Human-authored specs
    │   ├── mrd.md
    │   ├── prd.md
    │   └── uxd.md
    ├── gtm/                           # LLM-generated GTM docs
    │   ├── press.md
    │   ├── faq.md
    │   └── narrative.md
    ├── technical/                     # LLM-generated technical docs
    │   ├── trd.md
    │   ├── tpd.md
    │   └── ird.md
    ├── eval/                          # All evaluations
    │   ├── mrd.eval.json
    │   ├── prd.eval.json
    │   └── ...
    ├── .graphize/                     # Requirement graph
    ├── spec.md                        # Reconciled execution spec
    ├── current-truth.md               # Post-ship state
    ├── status.html                    # Readiness report
    ├── index.md                       # MkDocs page
    └── visionspec.yaml                 # Configuration

Working Backwards Flow

VisionSpec implements Amazon's Working Backwards methodology. Instead of starting with requirements and hoping they lead to a good customer experience, you start with the vision and work backwards:

1. MARKET PROBLEM (human-authored)
   mrd.md
       ↓
2. WORKING BACKWARDS (synthesized, editable)
   press.md  →  faq.md  →  prd.md
   (vision)     (scope)    (requirements)
       ↓
3. STAKEHOLDER REVIEW (synthesized, editable)
   narrative-1p.md / narrative-6p.md
       ↓
4. USER EXPERIENCE (human-authored)
   uxd.md
       ↓
5. TECHNICAL SPECS (synthesized, editable)
   trd.md  →  tpd.md  →  ird.md
   (design)   (tests)    (infra)
       ↓
6. RECONCILIATION
   All approved specs → spec.md
       ↓
7. AI EXECUTION
   spec.md → SpecKit | GSD | GasTown | GasCity
       ↓
8. POST-SHIP ALIGNMENT
   spec.md + reality → current-truth.md

Why this order? The Press Release defines the customer experience before any requirements are written. The FAQ challenges that vision and surfaces gaps. Only then is the PRD derived—grounded in a validated vision rather than abstract feature lists.

See Working Backwards for the full methodology.

CLI Commands

Full documentation: CLI Reference

Project Setup

Spec Workflow

Export & Integration

Execution Alignment

Cross-Project Analysis

Context & Traceability

Status Command

The status command shows project readiness with multiple output formats:

# Terminal output with readiness gates
visionspec status -p myproject

# JSON for programmatic use
visionspec status -p myproject --format json

# HTML report with traffic light indicator
visionspec status -p myproject --format html > status.html

# Markdown for embedding in docs
visionspec status -p myproject --format markdown

# CI mode - exits non-zero if not ready
visionspec status -p myproject --ci

Readiness Gates

MCP Server

VisionSpec includes an MCP (Model Context Protocol) server for integration with AI coding assistants like Claude Code and Kiro CLI.

# Run MCP server directly
visionspec-mcp

MCP Tools

Export Targets

Configuration Profiles

Profile (workflow) definitions — configurations, templates, and rubrics for all 25 default workflows — are embedded directly in this repo (pkg/workflows) and load as Go data with no filesystem access. VisionSpec includes two main types of profiles:

Stage-Based Profiles

For different product lifecycle stages:

Methodology Profiles

For different organizational methodologies:

The aws-two-way-door profile uses OpportunitySpec from prism-roadmap as the starting document instead of MRD, providing a 12-box canvas that combines discovery (Patton) with business case rigor (Cagan).

Using Profiles

# List available profiles
visionspec profiles list

# Show profile details
visionspec profiles show aws

# Initialize with a methodology profile
visionspec init my-product --profile aws

# Initialize with a stage profile
visionspec init my-feature --profile startup

# Export profile for customization
visionspec profiles export enterprise ./my-profile

# Initialize with custom profile directory
visionspec init my-project --profile-dir ./my-profile

Organization Customization

VisionSpec is designed for organizations to build their own prescriptive CLI tools. The open source version provides flexibility and choices; organization versions enforce standards.

Open Source vs. Organization

┌──────────────────────────────────────────────────────────┐
│                     Organization CLI                     │
│  (e.g., plexus-spec, acme-spec)                          │
│                                                          │
│  ┌────────────────┐  ┌─────────────┐  ┌───────────────┐  │
│  │ Org            │  │ Org         │  │ Org           │  │
│  │ Templates      │  │ Rubrics     │  │ Constitutions │  │
│  │ (prescriptive) │  │ (strict)    │  │ (defaults)    │  │
│  └────────┬───────┘  └──────┬──────┘  └───────┬───────┘  │
│           │                 │                 │          │
│           ▼                 ▼                 ▼          │
│  ┌────────────────────────────────────────────────────┐  │
│  │              ChainLoader (fallback)                │  │
│  └────────────────────────────────────────────────────┘  │
└─────────┬────────────────┬────────────────┬──────────────┘
          │                │                │
          ▼                ▼                ▼
┌──────────────────────────────────────────────────────────┐
│                     visionspec (OSS)                     │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ Default     │  │ Default     │  │ Built-in    │       │
│  │ Templates   │  │ Rubrics     │  │ App Types   │       │
│  │ (flexible)  │  │ (choices)   │  │ (generic)   │       │
│  └─────────────┘  └─────────────┘  └─────────────┘       │
└──────────────────────────────────────────────────────────┘

Building an Organization CLI

Organizations embed their resources and use ChainLoader to try org-specific first, falling back to visionspec defaults:

import (
    "embed"
    "github.com/ProductBuildersHQ/visionspec/pkg/cli"
    "github.com/ProductBuildersHQ/visionspec/pkg/constitution"
    "github.com/ProductBuildersHQ/visionspec/pkg/templates"
)

//go:embed templates/*.md
var orgTemplates embed.FS

//go:embed constitutions/**/*.yaml
var orgConstitutions embed.FS

func main() {
    root := &cobra.Command{Use: "org-spec"}
    cfg := cli.DefaultConfig()

    // Org templates first, fall back to visionspec defaults
    cfg.TemplateLoader = templates.NewChainLoader(
        templates.NewEmbedFSLoader(orgTemplates, "templates"),
        templates.EmbeddedLoader(),
    )

    // Org constitutions define defaults projects inherit
    cfg.ConstitutionLoader = constitution.NewEmbeddedLoader(
        orgConstitutions, "constitutions",
    )

    cli.AddCommandsTo(root, cfg)
    root.Execute()
}

Constitution Hierarchy

Constitutions define organizational defaults that flow down through inheritance:

org/plexusone.yaml          # Organization defaults
    ↓ inherits
team/platform-team.yaml     # Team overrides
    ↓ inherits
project/agentos.yaml        # Project-specific + exceptions

Example organization constitution:

apiVersion: visionspec/v1
kind: Constitution
metadata:
  name: plexusone
  level: organization

technical:
  languages:
    backend:
      primary: go
      allowed: [go, rust]
  tenancy:
    model: multi-tenant
    isolation: rls

infrastructure:
  iac:
    tool: pulumi
    language: go
  availability:
    target: "99.9"

See Organization Customization Guide and examples/org-cli/ for complete examples.

Ecosystem

VisionSpec is the ProductBuildersHQ spec stack's engine (visionstudio → visionspec): it executes workflows — scaffolding, LLM synthesis, LLM-as-Judge evaluation, lint, drift, status — against workflow definitions it now owns directly. The formal, JSON-Schema-backed contract those definitions are written against — workflow types, spec-type registry, templates, rubrics, provenance rules — lives here too, as the VisionSpec Specification (pkg/workflow, pkg/workflows, schema/; mirroring "Swagger" / "Swagger Specification"). It was previously incubated in a standalone repo (specification-workflow-spec) and has since been merged back in with full git history preserved.

• VisionStudio - The studio: LLM-powered app that imports VisionSpec's packages as its execution SDK

Dependencies

• structured-evaluation - Rubric and evaluation types
• graphize - Requirement graph extraction
• prism-roadmap - Canvas types (OpportunitySpec, BMC, OST) and templates

Development

# Build
make build

# Test
make test

# Lint
make lint

# Install locally
make install

Project Status

See ROADMAP.md for detailed implementation status and CHANGELOG.md for release history.

Current Version: v0.10.0

License

MIT