Skip to content

ProductBuildersHQ/visionspec

BranchesTags

Repository files navigation

VisionSpec

Go CI Go Lint Go SAST Go Report Card Docs Docs Visualization License

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

Command Description
init <project> Initialize a new project
create <type> Scaffold a new spec from template
lint [project] Validate directory structure
status Show project status and readiness
profiles <cmd> Manage configuration profiles

Spec Workflow

Command Description
eval [type] Evaluate specs using LLM judges
synthesize <type> Generate GTM/technical specs from sources
reconcile Generate unified execution spec
approve <type> Approve a spec for reconciliation

Export & Integration

Command Description
export <target> Export to target execution system
targets List available export targets
serve Start MCP server for AI integration
docs <cmd> Generate MkDocs documentation

Context & Traceability

Command Description
context <cmd> Gather codebase context
graph <cmd> Manage requirement graphs

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

Gate Description
Required specs present All required source specs (mrd, prd, uxd, trd) exist
Evaluations passing No blocking evaluation findings
Approvals obtained All required specs have approvals
Execution spec generated spec.md has been created

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

Tool Status Description
list_projects Implemented List all visionspec projects
get_project_status Implemented Get project readiness status
start_draft Implemented Initialize a new draft
update_draft Implemented Save draft content
eval_draft Implemented Evaluate draft against rubric
finalize_draft Implemented Promote draft to final spec
get_draft Implemented Retrieve current draft
discard_draft Implemented Delete a draft
get_spec Implemented Get specification content
get_eval Implemented Get evaluation results
run_eval Implemented Run evaluation against rubric
synthesize Implemented Generate a spec
reconcile Implemented Generate execution spec
approve Implemented Approve a specification
export Implemented Export to target system

Export Targets

Target Description
speckit GitHub Spec-Kit format
gsd Get Shit Done (PLAN.md, STATE.md)
gastown GasTown formulas and beads
gascity GasCity city.toml configuration
aidlc AWS AI-DLC Workflows (vision-document.md, technical-environment.md)
openspec OpenSpec portable format (future)

Configuration Profiles

VisionSpec includes two types of profiles:

Stage-Based Profiles

For different product lifecycle stages:

Profile Required Specs Use Case
0-1 hypothesis Idea validation phase
startup prd Pre-PMF startups
growth prd, uxd, faq 1-N scaling phase
enterprise mrd, prd, uxd, trd, press, faq, spec Post-PMF enterprises

Methodology Profiles

For different organizational methodologies:

Profile Methodology Best For
aws Working Backwards Customer-centric products (PR/FAQ, 6-pager)
google Design Docs + RFC Engineering-heavy orgs (OKRs, experiments)
stripe API-First Platform/API products (contract-first, DX)
lean-startup Build-Measure-Learn Early validation (hypothesis, MVP)
design-thinking Stanford d.school Human-centered design (empathy, prototyping)
jtbd Jobs to be Done Customer motivations (job statements, outcomes)

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

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

Phase Status
Phase 0: Foundation Complete
Phase 1: Directory Structure Complete
Phase 2: Evaluation Engine Complete
Phase 3: GTM & Technical Synthesis Complete
Phase 4: Reconciliation Engine Complete
Phase 5: Target Adapters Complete
Phase 6: Claude Code Integration Complete
Phase 7: Graphize Integration Complete
Phase 8: Advanced Features Not Started
Phase 9: Composability Complete
Phase 10: Platform Enhancements Not Started
Phase 11: Context Sources Complete
Phase 12: Methodology Profiles Complete

License

MIT

About

Multi-domain specification orchestration for humans and AI agents. MultiSpec bridges the gap between organizational intent (MRD, PRD, UXD) and executable specifications for AI coding agents.

productbuildershq.com/visionspec/

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 5

v0.5.0 Latest
May 26, 2026
+ 4 releases

Contributors

Languages