v0.4.0 Release Notes¶

Release Date: 2026-05-25

Overview¶

VisionSpec v0.4.0 introduces Context Sources for grounding spec synthesis in actual codebase data, a complete Reconciliation Engine with conflict detection, and target adapters for GSD, GasTown, and GasCity. This release also adds MkDocs documentation generation with graph metrics and profile export capabilities.

Highlights¶

Context Sources for grounding spec synthesis in actual codebase data
Reconciliation Engine with conflict detection and resolution
Target Adapters: GSD, GasTown, GasCity, SpecKit constitution sync
MkDocs documentation generation with graph metrics

Features¶

Context Sources¶

Ground technical spec synthesis in actual codebase data:

# visionspec.yaml
context:
  repositories:
    - path: "."
      include_structure: true
      include_deps: true
      include_apis: true

  graphize:
    enabled: true
    dir: ".graphize"

  files:
    - path: "docs/architecture.md"
      type: "architecture"
    - path: "docs/adr/*.md"
      type: "adr"

  mcp_servers:
    - name: "jira"
      command: "npx"
      args: ["-y", "@anthropic/mcp-jira"]
      tools: ["get_issue"]

Context CLI Commands:

# Gather context from configured sources
visionspec context gather

# Show context summary
visionspec context show

# Save snapshot for CI reproducibility
visionspec context save

# List configured sources
visionspec context sources

Reconciliation with Conflict Detection¶

The reconciliation engine now detects conflicts across specs:

Performance vs feature conflicts (PRD/TRD)
Security vs usability conflicts (UXD/TRD)
Scope vs timeline conflicts (MRD/PRD)
Missing traceability (requirements not covered in TRD)

# Run reconciliation with conflict detection
visionspec reconcile -p myproject

# Output includes spec.eval.json with:
# - Detected conflicts
# - Resolution decisions
# - Decision log

Target Adapters¶

Export to multiple execution systems:

Target	Output	Use Case
`speckit`	spec.md, plan.md, tasks.md	GitHub Spec-Kit workflows
`gsd`	PLAN.md, STATE.md, config.json	Get Shit Done methodology
`gastown`	formula.toml, beads	Multi-agent formulas
`gascity`	city.toml	Multi-agent city orchestration

# Export to GSD format
visionspec export gsd -p myproject

# Export to GasTown
visionspec export gastown -p myproject

# Export with constitution sync (SpecKit)
visionspec export speckit -p myproject

MkDocs Documentation Generation¶

Generate MkDocs-compatible documentation:

# Generate index.md for all projects
visionspec docs generate

# Generate with graph metrics
visionspec docs generate --with-graph

# Generate for specific project
visionspec docs project myproject

Spec Scaffolding¶

Create new specs from templates:

# Create a new MRD
visionspec create mrd -p myproject

# Create a TRD (force overwrite)
visionspec create trd -p myproject --force

Profile Export¶

Extract profiles for customization:

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

# Use custom profile
visionspec init my-project --profile-dir ./my-profile

CONSTITUTION.md Multi-Location¶

Constitution files are discovered automatically:

Repo-level: docs/specs/CONSTITUTION.md
Org-level: ~/.config/visionspec/CONSTITUTION.md

GraphMetrics in Status Reports¶

Status reports now include traceability metrics:

visionspec status -p myproject

# Shows:
# - Total requirements, user stories, constraints
# - Trace coverage percentage
# - Conflict count

Custom Rubrics Configuration¶

Configure rubrics per-project in visionspec.yaml:

rubrics:
  directory: "./rubrics"
  overrides:
    prd: "./custom-prd.rubric.yaml"
  strict_mode: true
  max_critical: 0
  max_high: 2

New Commands¶

Command	Description
`create <type>`	Scaffold a new spec from template
`docs generate`	Generate MkDocs index files
`docs project <name>`	Generate index for specific project
`context gather`	Fetch context from configured sources
`context show`	Display context summary
`context save`	Save context snapshot
`context sources`	List configured sources
`profiles export`	Export profile for customization

Installation¶

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

Migration Guide¶

No breaking changes. Existing projects continue to work.

To use new features:

Context Sources: Add context section to visionspec.yaml
Custom Rubrics: Add rubrics section to visionspec.yaml
Profile Export: Use visionspec profiles export to extract and customize

What's Next¶

See ROADMAP.md for planned features including:

Phase 8: Advanced Features (versioning, cross-project analysis)
AI Co-Authoring workflow enhancements
OpenSpec target adapter
CI/CD integration (GitHub Actions, pre-commit hooks)