Multi-domain specification orchestration for humans and AI agents.
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)
- ✍️ Domain-specific authoring - Separate specs for PM, UX, Engineering
- ⚙️ LLM synthesis - Generate Press, FAQ, PRD, TRD, 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.
go install github.com/ProductBuildersHQ/visionspec/cmd/visionspec@v0.4.0# 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.htmldocs/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
│ └── 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
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 → ird.md
↓
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.
Full documentation: CLI Reference
| 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 |
| 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 |
| 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 |
| Command | Description |
|---|---|
context <cmd> |
Gather codebase context |
graph <cmd> |
Manage requirement graphs |
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| 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 |
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| 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 |
| 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 |
openspec |
OpenSpec portable format (future) |
Profiles define which specs are required for different product lifecycle stages:
# List available profiles
visionspec profiles list
# Show profile details
visionspec profiles show startup
# Export profile for customization
visionspec profiles export enterprise ./my-profile
# Initialize with a profile
visionspec init my-project --profile startup
# Initialize with custom profile directory
visionspec init my-project --profile-dir ./my-profile| 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 |
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.
- structured-evaluation - Rubric and evaluation types
- graphize - Requirement graph extraction
# Build
make build
# Test
make test
# Lint
make lint
# Install locally
make installSee ROADMAP.md for detailed implementation status and CHANGELOG.md for release history.
Current Version: v0.4.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 |
MIT