A self-evolving meta-framework that converts uncertain visions into evidenced, traceable, production systems — for any output type, across any time horizon, with humans and AI agents as co-operators.
Read docs/VISION2PROD_CHARTER.md first. It is the constitution — the invariants that anchor every future evolution of this framework. Everything else may change; the charter does not.
Then read docs/VISION.md for the 10-year destination and the five strategic arcs.
VisionForge → SOTAForge → DesignForge → BuildForge
| Stage | Responsibility |
|---|---|
| VisionForge | Clarify and score the vision; output a structured opportunity brief and research questions |
| SOTAForge | Research state of the art, identify gaps, derive capabilities, produce PRD and build plan |
| DesignForge | Convert research outputs into canonical design truth, accepted ADRs, and build packs |
| BuildForge | Implement, test, document, and produce implementation evidence |
Gate integrity is enforced by the deterministic verifier (vision2prod_core/verifier.py): schema-valid ∧ evidence-tagged ∧ traceability-intact ∧ cycle-status-valid ∧ build-evidence-present ∧ stage-ordering-valid. Zero LLM calls.
Start here:
docs/QUICKSTART.md— go from a new idea to a gated, evidenced dossier in minutes, offline and free, via the browser portal or the CLI.
Fastest path — start a new experiment from the CLI (offline, no API key, no cost):
uv sync
uv run v2p new my-idea --idea "Your idea in one sentence."
uv run v2p run --idea clients/my-idea/inputs/idea_seed.json --service full --offline \
--out clients/my-idea/runs/first
cat clients/my-idea/runs/first/dossier.md # your dossier + gate decisionOr drive it from the browser — run launcher, live console, dossier library, gate override, config:
uv sync --extra portal
uv run v2p-portal # → http://127.0.0.1:8000Want just one department's work (market gap, SOTA + gap, architecture, build)? Add
--service <name> — see the Quick Start §4 and uv run v2p services.
Working on the framework itself (not a new idea)?
v2p init <name>scaffolds a self-improvement cycle underself/cycles/;v2p voice-importimports a voice note.
One company, filed by kind — same place for same things. Three categories live here and never mix: the platform (how the company works), the self-improvement project (self/ — Vision2Prod as its own client: self/cycles/ + self/vision/), and external client engagements (clients/). See docs/REPOSITORY_MAP.md.
vision2prod/
├── README.md CHANGELOG.md ROADMAP.md CLAUDE.md # entry docs
├── docs/ # ALL docs: CHARTER, VISION, GOVERNANCE, PIPELINE, adr/, diagrams/
├── vision2prod_core/ # the engine (code): verifier, CLI (v2p), execution/, registry, …
│
│ # ── the company model: people / methods / tools (see docs/MODEL.md) ──
├── people/ # WHO — every expert, identical markdown SKILL.md:
│ ├── office-of-the-chair/<role>/SKILL.md # CEO, CTO, chief of staff, quality, visionary
│ ├── business/<department>/<role>/SKILL.md # discovery, strategy+marketing, finance, legal, IC
│ ├── science_engineering/<department>/<role>/ # research-science, architecture, engineering
│ └── cross_cutting/<role>/ + roster.yaml
├── methods/ # HOW — procedures (*.yaml) + stage bundles
│ │ # methods/{visionforge,sotaforge,designforge,buildforge}/ (installable skills)
├── tools/ # WHAT THEY RUN — all Python + MCP: gates/, export/ (+ future arxiv_fetch/)
├── contracts/ # ALL schemas (JSON Schema, *.schema.json)
├── services/ # the service catalog (DAGs): full venture + the 4 service lines
├── gates/ render/ # go/no-go gate spec; dossier presentation template
├── examples/ # idea seeds + priors
├── config.yaml # run config (points the engine at the dirs above)
│
├── arcs/ stages/ templates/ # framework spec + data (the platform)
├── self/ # category 2 — Vision2Prod as its own client (self-improvement)
│ ├── cycles/ # numbered self-application cycles (0001–0022)
│ └── vision/versions/ # versioned vision + charter history
├── clients/ # category 3 — external client engagements (one dir per client)
├── portal/ tests/
BuildForge uses a pluggable registry (vision2prod_core/artifact_registry.py). Built-in types:
artifact_type |
Gate | Status |
|---|---|---|
code |
Passes vacuously; quality checked via quality_gate_results | Functional |
policy_bundle |
≥1 YAML, all parse, title+description required, ≥1 has version | Functional |
simulation_spec |
title+desc+model_type; ≥1 param (name+desc); ≥1 output; reproducibility.method | Functional |
spatial_spec |
title+desc+platform; ≥1 interaction_protocol (name+desc); ≥1 spatial_anchor (id+desc) | Functional |
model_contract |
model_name+desc+task; ≥1 performance_budget (metric_name+threshold); latency_budget_ms; ≥1 fairness_consideration | Functional |
To add a new type: create an ArtifactTypeSpec and call artifact_registry.register(spec) in artifact_registry.py. Follow model_contract or spatial_spec as patterns.
uv run v2p gate [CYCLE_DIR] # run verifier; exit 0 on pass/watch, 1 on fail
uv run v2p status [--json] # cycle table + arc phase summary
uv run v2p init <name> # scaffold a new cycle directory
uv run v2p compat [DIR] # backward-compat validator; exit 0/1
uv run v2p measure-context <arc_id> # token overhead: fresh read vs context file
uv run v2p voice-import [FILE] # scaffold VisionForge cycle from voice transcript
--notes-md # read latest entry from ~/notes.md (YazSes format)
--cycle-name NAME # slug for the new cycle (default: voice-cycle)
uv run v2p services # list the company's service lines
uv run v2p run # run the company on an idea (a service line) [alias: v2p venture run]
--idea SEED.json | --brief BRIEF.yaml # input: raw idea seed or a V2P opportunity_brief
--offline # canned schema-valid artifacts (no API key, no cost)
--provider {anthropic,azure} # live model provider behind the seam
--service {full,foresight,market,sota-gap,architecture,build} # order PART of the firm, not only the full venture
--prior ARTIFACT.json # seed an upstream artifact (repeatable); needed by downstream-only services
--out DIR # output: venture_state.json + dossier.md / service_report.md (default ./venture_out)Service lines — engage the firm for one department's work instead of the full venture:
--service market (market gap), sota-gap (SOTA + gap analysis), architecture (CTO/architecture
pack; --prior feasibility_report.json), build (implementation; --prior build_queue.json), or
full (the whole council, default). See docs/adr/ADR-E-firm-service-lines.md.
A unified, local operator console over the whole system — governance (arcs · cycles ·
verifier · traceability) and the venture runtime — built as a strictly additive layer:
the repo + git + v2p CLI remain the single source of truth. Python-only (FastAPI + Jinja +
HTMX), no Node/build step.
uv sync --extra portal
uv run v2p-portal [--host 127.0.0.1] [--port 8000] [--repo-root .]P0 is the read-only spine: a curl-able JSON API under /api plus brand-styled views
(Overview, Cycle/Arc explorers, Verifier & Gates, Traceability, Unified Pipeline as live
Cytoscape DAGs, and the Firm org chart). P1 (shipped) adds the company showcase —
browse Services (the orderable service lines), Methods, and Tools — and the
run launcher: pick a service, enter a client + idea, and launch it for a client straight
from the browser. Each run is an isolated v2p run subprocess writing to
clients/<slug>/runs/<run_id>/, with a live console and an output viewer for the produced
dossier / service report. The web process never imports the execution engine or the model
SDK (core-purity) — it shells out to the CLI. Gate override and config write-back are P2–P3
(see .claude/plans/).
uv sync # install Python dependencies
make install-skills # symlink skills into ~/.claude/skills/The skills are then available in any Claude Code session as /vision2prod-visionforge, /vision2prod-designforge, /vision2prod-buildforge.
uv run pytest --tb=short -q # 657 tests (v1.9.0)
uv run ruff check tools vision2prod_core portal tests
uv run mypy tools vision2prod_core portal
uv run v2p gate self/cycles/0001-stage-skills
uv run v2p gate self/cycles/0002-cycle-status-schema
uv run v2p gate self/cycles/0003-multi-cycle-primitives
uv run v2p gate self/cycles/0004-artifact-type-registry
uv run v2p gate self/cycles/0005-cli-tool
uv run v2p gate self/cycles/0006-oq06-phase-gates
uv run v2p gate self/cycles/0007-charter-compliance-gate
uv run v2p gate self/cycles/0008-simulation-artifact-type
uv run v2p gate self/cycles/0009-vision-revision-protocol
uv run v2p gate self/cycles/0010-arc-contract-retroactive
uv run v2p gate self/cycles/0011-backward-compat-validation
uv run v2p gate self/cycles/0012-spatial-artifact-type
uv run v2p gate self/cycles/0013-model-contract-artifact-type
uv run v2p gate self/cycles/0014-arc-deferral-protocol
uv run v2p gate self/cycles/0015-a3-multi-agent-protocol
uv run v2p gate self/cycles/0016-a3-human-override-semantics
uv run v2p gate self/cycles/0017-a3-persistent-agent-context
uv run v2p gate self/cycles/0018-a3-phase2-concurrent-execution
uv run v2p gate self/cycles/0019-a3-phase4-empirical-measurement
uv run v2p gate self/cycles/0020-a5-voice-visionforgeThe export tool emits skills in formats compatible with other Agent Skills-supporting tools.
python -m tools.export methods/visionforge \
--target all --out /tmp/v2p-export/
# Targets: agent-skills, agentcard, mcp, all| Arc | Status | Open phases |
|---|---|---|
| A1 — Beyond Software | complete | — |
| A2 — Strategic Arcs as Primitives | complete | — |
| A3 — AI-Native Co-operation | complete | — |
| A4 — Self-Evolution Discipline | active (perpetual — charter invariant) | — |
| A5 — New Mediums of Intent | active | phase-2 through phase-5 (technology deferred 2029–2035) |
Vision2Prod was designed to answer one question:
How do you reliably go from a vague idea to production code without losing context, evidence, or decision rationale?
The framework enforces evidence gates at each stage boundary so that nothing moves forward without written justification. The pipeline shape is the same regardless of output type — code, policy bundles, simulations, spatial AR specs, model contracts, or artifact types that don't yet exist.