MVP Operating System

An AI-assisted operating layer for taking ideas to verified MVPs with product gates, independent review, automated checks, and explicit human decisions.

Public repository: https://github.com/skoskov/mvp-operating-system

What it demonstrates

• Product and market work is resolved before implementation.
• Technical artifacts receive independent review.
• Verification and release gates are part of the workflow.
• The system keeps the human focused on product, business, risk, cost, scope, and important technical trade-offs.

Core loop

flowchart LR
  A[Idea] --> B[Research]
  B --> C[Design and metrics]
  C --> D[Build and review]
  D --> E[Verification]
  E --> F[Iteration]

Loading

Purpose

This system keeps the human focused on high-value product, business, risk, cost, scope, and important technical trade-off decisions.

It must not use the human as a terminal operator, log copier, code reviewer, long-spec approver, QA engineer, or checklist validator.

Core flow

Every project startup first resolves current truth through Project Control v2:

python3 .agents/skills/mvp-operating-system/bin/project_control.py bootstrap --project-root .

This prevents preserved but superseded decisions from silently becoming active in a new chat. See docs/project-control-v2.md.

1. Start from a high-level idea.
2. Create a mandatory Idea Intake.
3. Create mandatory Launch Market Research.
4. Create mandatory Brand / Design System / UX Flow.
5. Run Standard Stack / Environment Preflight.
6. Run Memory Preflight from the Obsidian LLM Knowledge Base.
7. Validate the proportional Outcome-First / Reuse-First task contract.
8. Create Analytics / Observability Plan.
9. Create Support / Feedback / User Operations.
10. Optionally create Limited Release / Launch Plan for closed beta, controlled test, or explicit GTM request.
11. Create Build / Deploy / Verification Plan.
12. Ask the human only short Decision Cards when needed.
13. Present Token/Time Budget before expensive work.
14. Create OpenSpec proposal/spec/tasks.
15. Run independent review for technical artifacts.
16. Give Codex small approved implementation slices.
17. Codex implements, runs commands, verifies, and repairs failures.
18. Run QA / Acceptance / Release Gate and final task-contract validation.
19. Run Pre-launch Iteration Update.
20. Update Build / Deploy / Verification Plan and continue with the next implementation slice until the owner explicitly says the MVP is ready to launch.
21. Run final PR review with Codex GitHub Review.
22. Update Obsidian memory with decisions, failures, defaults, token/time usage, and lessons learned.

Repository contents

/global/AGENTS.md
/global/standard-stack.md
/skill/mvp-operating-system/
/template/mvp-project-template/
/obsidian/vault-template/
/docs/how-to-start-new-mvp.md
/docs/operating-principles.md
/docs/codex-multiagent-protocol.md
/docs/project-control-v2.md

How to use

For every new MVP, do not manually run 10 setup commands. Give only the project name and run one bootstrap script from this repository.

Windows PowerShell:

.\scripts\new-mvp.ps1 relationship-agent-mvp

WSL/bash:

./scripts/new-mvp.sh relationship-agent-mvp

The script creates the project under C:\Users\skoskov\Documents\_DEV, copies the MVP template, initializes Git, creates the first commit, and pushes to GitHub when gh is installed and authenticated.

Do not start from a blank chat or blank repository.

Versioned project sync

MVP OS releases are tracked in VERSION, CHANGELOG.md, and compatibility/projects.json. Active projects use mvp-os.lock and the template MVP OS Sync workflow to receive reviewed pull requests for managed operating-layer files. See docs/mvp-os-sync.md for the contract.

Continuous context sync

Projects persist requirements, corrections, decisions, and handoffs in the single canonical skoskov/context repository. The distributed context_sync.py runner performs pull-first preflight and automatic message-log commit/push. See docs/context-sync.md.

This source repository also self-hosts Project Control through root AGENTS.md, mvp-os.lock, and project-control/CURRENT.json. Its lock uses the source role and never runs downstream self-sync. A local VERSION with publication_status: candidate is not an official release. This source repository also self-hosts Project Control through root AGENTS.md, mvp-os.lock, and project-control/CURRENT.json. Its lock uses the source role and never runs downstream self-sync. A local VERSION with publication_status: candidate is not an official release.

Limits

This repository is an operating system for product and engineering work. It does not prove product-market fit by itself; outcomes still depend on the project, evidence, execution, and verification.