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)
• 🎯 Methodology profiles - AWS, Google, Stripe, Lean Startup, Design Thinking, JTBD
• ✍️ 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 customizable rubrics
• 🔄 Reconciliation - Conflict detection and tradeoff resolution
• 📦 Target adapters - Export to SpecKit, GSD, GasTown, GasCity, 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.5.0

Quick Start

# Initialize a new project
visionspec init user-onboarding

# Validate project structure
visionspec lint

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

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

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

VisionSpec includes two types of profiles:

Stage-Based Profiles

For different product lifecycle stages:

Methodology Profiles

For different organizational methodologies:

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

CLI as Library

Organizations can build custom CLI tools using visionspec as a library:

import (
    "github.com/ProductBuildersHQ/visionspec/pkg/cli"
    "github.com/ProductBuildersHQ/visionspec/pkg/profiles"
)

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

    // Load a profile
    profile, _ := profiles.DefaultLoader().Load("enterprise")
    cfg := cli.ConfigFromProfile(profile)

    // Add visionspec commands
    cli.AddCommandsTo(root, cfg)

    root.Execute()
}

See examples/ for complete organization CLI examples.

Dependencies

• structured-evaluation - Rubric and evaluation types
• graphize - Requirement graph extraction

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

License

MIT