ventureos 1.0.0

package/README.md

@@ -0,0 +1,149 @@
+# VentureOS
+
+**A multi-agent AI framework for structured venture building.**
+
+VentureOS guides teams from a raw domain or idea all the way to an investor-ready pitch — through a structured 12-week incubation process powered by specialized AI agents.
+
+---
+
+## Install
+
+```bash
+npx ventureos install
+```
+
+The installer asks 5 questions (your name, AI tool, language, research depth, execution mode), then sets up the full framework in your project in under 30 seconds.
+
+**Requirements:** Node.js 18+
+
+**Works with:** Claude Code, Cursor, Windsurf, and any other AI coding tool.
+
+---
+
+## What VentureOS Does
+
+- Tracks where your venture is in the incubation journey
+- Routes you to the right specialist agent for each phase
+- Generates first drafts of every deliverable so you never start from a blank page
+- Enforces evidence-based progression: guiding questions must be answered before advancing
+- Manages two decision gates where ventures are evaluated for continuation, pivot, or kill
+
+---
+
+## How It Works
+
+VentureOS is a collection of AI agent files and workflow files that you load into your preferred AI coding assistant. The agents collaborate through a shared venture state file to guide you through the full incubation lifecycle.
+
+**Entry points:**
+- **Domain exploration** — You have a domain (e.g., "energy management"). VentureOS maps the opportunity landscape first, then moves into incubation.
+- **Idea development** — You have a specific idea. VentureOS jumps directly into incubation.
+
+**Final output:** Investor-ready pitch deck (Markdown + Excalidraw) or a documented pivot/kill decision with full rationale and archived artifacts.
+
+---
+
+## The Incubation Journey (12 Weeks)
+
+```
+Week 1          Weeks 2-3           Weeks 4-7              Weeks 10-12
+┌──────────┐   ┌──────────────┐   ┌────────────────────┐  ┌──────────────────┐
+│ SETUP    │   │ UNDERSTAND   │   │ DEFINE SOLUTION    │  │ DESIGN BUSINESS  │
+│ THE TEAM │   │ THE MARKET   │   │                    │  │                  │
+└──────────┘   │              │   │                    │  │                  │
+               │ FIND         │   │ BUILD INITIAL      │  │                  │
+               │ CUSTOMER     │──▶│ BUSINESS CASE      │──▶│                  │
+               │ PAIN         │   │                    │  │                  │
+               └──────────────┘   └──────┬─────────────┘  └────────┬─────────┘
+                                         │                          │
+                                    CHECK-IN PITCH             FINAL PITCH
+                                    to Venture Board           to Venture Board
+                                    (Go/Pivot/Kill)            (Go/Pivot/Kill)
+```
+
+---
+
+## The Agents
+
+| Agent | Name | Role |
+|-------|------|------|
+| `venture-master.md` | Victor | Orchestrator — load this first |
+| `agents/domain-explorer.md` | Diana | Market & domain research |
+| `agents/customer-discovery.md` | Clara | Customer pain & interviews |
+| `agents/product-strategist.md` | Paulo | Wedge design & prototyping |
+| `agents/business-architect.md` | Bernard | Business model & revenue |
+| `agents/financial-analyst.md` | Fiona | Market sizing & financial modeling |
+| `agents/venture-evaluator.md` | Eva | Venture Board gate evaluation |
+| `agents/pitch-master.md` | Petra | Pitch deck creation |
+| `agents/growth-strategist.md` | Grace | GTM & market experiments |
+| `agents/venture-ops.md` | Olivia | Team setup & parent org alignment |
+
+---
+
+## Directory Structure
+
+```
+ventureOS/
+├── venture-master.md          ← START HERE — load this file first
+├── workflow-engine.md         ← Workflow execution engine
+├── config.yaml                ← Your configuration (edit before first use)
+├── README.md                  ← This file
+├── SETUP.md                   ← Installation guide
+├── agents/                    ← Specialist agents (loaded on demand)
+│   ├── domain-explorer.md
+│   ├── customer-discovery.md
+│   ├── product-strategist.md
+│   ├── business-architect.md
+│   ├── financial-analyst.md
+│   ├── venture-evaluator.md
+│   ├── pitch-master.md
+│   ├── growth-strategist.md
+│   └── venture-ops.md
+├── workflows/                 ← Phase-specific workflow definitions
+│   ├── 0-explore/
+│   ├── 1-setup-team/
+│   ├── 2-understand-market/
+│   ├── 3-find-pain/
+│   ├── 4-define-solution/
+│   ├── 5-business-case/
+│   ├── 6-design-business/
+│   └── venture-status/
+├── templates/                 ← Output document templates (30+)
+├── scoring/                   ← Gate rubric, pain scoring, pivot triggers
+├── techniques/                ← Brainstorming techniques, synthetic tools
+└── _memory/
+    └── venture-state.yaml     ← Active venture state (auto-managed)
+```
+
+Outputs are saved to: `_ventures/{venture_name}/`
+
+---
+
+## Quick Start
+
+1. Edit `ventureOS/config.yaml` — add your name, venture name, preferred language
+2. Load `ventureOS/venture-master.md` into your AI tool (see `SETUP.md` for your specific tool)
+3. Victor greets you, shows the phase-aware menu, and asks what you want to work on
+4. Type a command or number — Victor routes you to the right agent and workflow
+
+See `SETUP.md` for detailed installation instructions for Claude Code, Cursor, Windsurf, and other tools.
+
+---
+
+## Two Execution Modes
+
+**Guided mode (default):** The agent pauses at each checkpoint, shows you the output, and waits for your approval before proceeding. Best for real ventures where strategic decisions matter.
+
+**Yolo mode:** The agent runs the full workflow autonomously and presents all outputs at the end for batch review. Best for rapid idea screening.
+
+Set your preferred default in `config.yaml` or switch modes per workflow.
+
+---
+
+## Pivot & Kill Mechanism
+
+VentureOS tracks every pivot and kill decision:
+
+- **Pivot:** Archives current artifacts, classifies pivot type (customer/problem/solution/model/market), identifies re-entry phase, preserves relevant work
+- **Kill:** Documents learnings, archives all artifacts, marks venture as killed with full rationale
+
+Pivot history is preserved in `ventureOS/_memory/venture-state.yaml`.

package/SETUP.md

@@ -0,0 +1,193 @@
+# VentureOS Setup Guide
+
+## Step 1 — Configure VentureOS
+
+Open `ventureOS/config.yaml` and fill in your details:
+
+```yaml
+user_name: "Your Name"          # How agents will address you
+venture_name: ""                # Leave blank to start a new venture
+communication_language: "English"
+output_folder: "_ventures"      # Where outputs are saved
+research_depth: "standard"      # light | standard | deep
+llm: "claude-code"              # claude-code | cursor | windsurf | other
+default_mode: "guided"          # guided | yolo
+```
+
+**That is the only file you need to edit before your first session.**
+
+---
+
+## Step 2 — Load VentureOS (by tool)
+
+### Claude Code
+
+```bash
+# From your project root, load the orchestrator:
+claude venture-master.md
+```
+
+Or reference it in a conversation:
+```
+@ventureOS/venture-master.md
+```
+
+To load a specialist agent directly:
+```
+@ventureOS/agents/domain-explorer.md
+```
+
+### Cursor
+
+In the chat panel, attach the file:
+- Click the paperclip icon → select `ventureOS/venture-master.md`
+
+Or type in chat:
+```
+Load @ventureOS/venture-master.md and activate Victor.
+```
+
+To load a specialist directly:
+```
+Load @ventureOS/agents/customer-discovery.md and activate Clara.
+```
+
+### Windsurf
+
+In the Cascade panel:
+```
+Load the file ventureOS/venture-master.md and follow the activation instructions.
+```
+
+To load a specialist:
+```
+Load ventureOS/agents/domain-explorer.md and follow the activation instructions.
+```
+
+### Other AI Tools (ChatGPT, Gemini, etc.)
+
+1. Open `ventureOS/venture-master.md` in a text editor
+2. Copy the full file contents
+3. Paste into a new conversation as the first message
+4. The agent will activate and guide you from there
+
+For specialist agents: copy the contents of the relevant file in `ventureOS/agents/` and paste to activate.
+
+---
+
+## Step 3 — First Session
+
+When you load `venture-master.md`, Victor (the orchestrator) will:
+
+1. Read your `config.yaml`
+2. Load venture state from `_memory/venture-state.yaml`
+3. Greet you and display the venture status banner
+4. Show the phase-aware menu
+5. Wait for your input
+
+**If this is your first venture**, type `NV` (New Venture) and Victor will guide you through setup.
+
+**If you have an existing venture**, Victor will pick up where you left off based on the saved state.
+
+---
+
+## Step 4 — Understanding the Menu
+
+Victor's main menu:
+
+| Command | Description |
+|---------|-------------|
+| `VS` | Venture Status — current phase, answered questions, artifacts |
+| `NV` | New Venture — start a new venture (domain or idea entry) |
+| `EX` | Explore Domain — opportunity discovery (pre-incubation) |
+| `ST` | Setup the Team — team charter, parent org alignment (Phase 1) |
+| `UM` | Understand the Market — competitive landscape, sizing (Phase 2) |
+| `FP` | Find Customer Pain — discovery, synthesis, journey map (Phase 3) |
+| `DS` | Define the Solution — wedge design, prototyping (Phase 4) |
+| `BC` | Build Business Case — risks, experiment plan, check-in pitch (Phase 5) |
+| `DB` | Design the Business — business model, GTM, final pitch (Phase 6) |
+| `NVB` | Board Feedback — on-demand synthetic venture board feedback |
+| `AG` | Agents — view all specialists and how to activate them |
+| `CH` | Chat — free discussion with Victor |
+| `DA` | Dismiss Agent |
+
+You can type the command code (e.g., `FP`) or a natural language match (e.g., "customer pain", "find pain", "interviews").
+
+---
+
+## Step 5 — Loading Specialist Agents
+
+When Victor routes you to a specialist, he will tell you which agent to load and how (based on your `llm` setting in `config.yaml`).
+
+You can also load specialists directly at any time:
+
+| Specialist | File |
+|-----------|------|
+| Victor (Orchestrator) | `ventureOS/venture-master.md` |
+| Diana (Market Research) | `ventureOS/agents/domain-explorer.md` |
+| Clara (Customer Discovery) | `ventureOS/agents/customer-discovery.md` |
+| Paulo (Product Strategy) | `ventureOS/agents/product-strategist.md` |
+| Bernard (Business Model) | `ventureOS/agents/business-architect.md` |
+| Fiona (Financial Analysis) | `ventureOS/agents/financial-analyst.md` |
+| Eva (Venture Board) | `ventureOS/agents/venture-evaluator.md` |
+| Petra (Pitch Creation) | `ventureOS/agents/pitch-master.md` |
+| Grace (GTM & Growth) | `ventureOS/agents/growth-strategist.md` |
+| Olivia (Team & Ops) | `ventureOS/agents/venture-ops.md` |
+
+---
+
+## Output Files
+
+All VentureOS outputs are saved to:
+```
+_ventures/{venture_name}/
+```
+
+Example output structure after a full incubation run:
+```
+_ventures/my-venture/
+├── venture-canvas.md
+├── team-charter.md
+├── mothership-asset-map.md
+├── market-sizing.md
+├── competitive-analysis.md
+├── interview-scripts/
+├── interview-synthesis.md
+├── pain-atomization.md
+├── pain-journey-map.md
+├── icp-profile.md
+├── wedge-definition.md
+├── value-proposition.md
+├── solution-feasibility.md
+├── business-model-canvas.md
+├── financial-model.md
+├── gtm-plan.md
+├── experiment-plan.md
+├── pitch/
+│   ├── checkin-pitch.md
+│   ├── pitch-deck.md
+│   └── excalidraw-frames.md
+└── pivots/              ← only if pivot was triggered
+    └── pivot-1/
+```
+
+---
+
+## Tips
+
+**Guided vs Yolo mode**
+- Guided: agent pauses at each step for your review. Best for real ventures.
+- Yolo: agent runs everything and presents all outputs at once. Best for rapid screening of multiple ideas.
+
+**Resuming a session**
+- VentureOS saves state to `ventureOS/_memory/venture-state.yaml` after each step.
+- Load `venture-master.md` at the start of any session — Victor reads the state and picks up where you left off.
+
+**Multiple ventures**
+- Change `venture_name` in `config.yaml` to switch between ventures.
+- Each venture's state is tracked separately in `venture-state.yaml`.
+
+**Research depth**
+- `light` — high-level overview, fast. Good for early screening.
+- `standard` — structured analysis with sourced data. Recommended for real incubation.
+- `deep` — exhaustive multi-source research with cross-validation. Best for high-stakes decisions.

package/_memory/venture-state.yaml

@@ -0,0 +1,142 @@
+# VentureOS Venture State
+# This file is managed automatically by VentureOS agents.
+# Do not edit manually unless you know what you are doing.
+# ─────────────────────────────────────────────────────────
+
+venture_name: ""
+current_phase: ""          # 0-explore | 1-setup-team | 2-understand-market | 3-find-pain | 4-define-solution | 5-business-case | 6-design-business
+current_week: 0
+entry_point: ""            # domain | idea
+started: ""                # ISO date: YYYY-MM-DD
+status: ""                 # active | pivoted | killed | funded
+
+# Progress across three activity categories
+category_progress:
+  team: "not-started"        # not-started | in-progress | complete
+  venture: "not-started"     # not-started | in-progress | complete
+  mothership: "not-started"  # not-started | in-progress | complete
+
+# Working hypotheses — updated as evidence accumulates
+hypotheses:
+  customer: ""
+  problem: ""
+  solution: ""
+  wedge: ""
+
+# Guiding questions tracker — one entry per question per phase
+guiding_questions:
+  explore: []
+  setup:
+    - question: "What is the Venture's reason to exist?"
+      answered: false
+      evidence: ""
+    - question: "What software and tools do we use? What is our weekly cadence?"
+      answered: false
+      evidence: ""
+    - question: "Who is in our team? Who is our sponsor? Who supports us?"
+      answered: false
+      evidence: ""
+    - question: "Does the venture team know which parent organization capabilities can be leveraged?"
+      answered: false
+      evidence: ""
+  market:
+    - question: "Is the market large and growing? What are the potential barriers to entry?"
+      answered: false
+      evidence: ""
+    - question: "Who matters most? Who most likely has the primary pain to solve?"
+      answered: false
+      evidence: ""
+    - question: "What is the size of the market? (# customers, market value, geographic hot spots)"
+      answered: false
+      evidence: ""
+    - question: "What companies and products currently operate in the market?"
+      answered: false
+      evidence: ""
+    - question: "Does the team understand the broader context and goals their customer operates in?"
+      answered: false
+      evidence: ""
+  pain:
+    - question: "Can the team prioritize the most important pain to solve?"
+      answered: false
+      evidence: ""
+    - question: "Is the pain frequent, intense, and/or prevalent enough to support a business?"
+      answered: false
+      evidence: ""
+    - question: "Has the team validated the pain exists? Can they identify their ideal customer?"
+      answered: false
+      evidence: ""
+    - question: "Does the team understand who the buyer is (if different to the user)?"
+      answered: false
+      evidence: ""
+  solution:
+    - question: "Can the team describe the wedge (smallest part that can be quickly brought to market)?"
+      answered: false
+      evidence: ""
+    - question: "Can the team articulate the big vision for the product/service?"
+      answered: false
+      evidence: ""
+    - question: "Is the solution technically feasible? Can it be built (build, buy, partner, invest)?"
+      answered: false
+      evidence: ""
+    - question: "What makes the solution special and what new value does it provide?"
+      answered: false
+      evidence: ""
+    - question: "Does the team have a hypothesis for how the solution scales from wedge to big vision?"
+      answered: false
+      evidence: ""
+    - question: "Can the target customer use the product? Do they find value in it?"
+      answered: false
+      evidence: ""
+  business_case:
+    - question: "Has the board reviewed venture progress and agreed the venture should continue?"
+      answered: false
+      evidence: ""
+    - question: "Has the team defined an operating/experiment plan for the next phase?"
+      answered: false
+      evidence: ""
+    - question: "Does the team have a pipeline of eager pilot customers?"
+      answered: false
+      evidence: ""
+  design_business:
+    - question: "Has the team defined diverse and robust revenue streams?"
+      answered: false
+      evidence: ""
+    - question: "Are desirability scores, CAC, and signup rates strong enough to support a healthy business?"
+      answered: false
+      evidence: ""
+    - question: "Can the team attract users via marketing or sales? Convert pilot users?"
+      answered: false
+      evidence: ""
+
+# Completed artifacts — updated after each workflow step
+completed_artifacts: []
+# Format:
+# - name: "artifact-name"
+#   path: "_ventures/{venture_name}/artifact-name.md"
+#   phase: "1-setup-team"
+#   date: "YYYY-MM-DD"
+
+# Decision gate history
+gate_history:
+  - gate: "checkin"
+    date: null
+    score: null
+    decision: null   # GO | PIVOT | KILL | null
+    notes: ""
+  - gate: "final"
+    date: null
+    score: null
+    decision: null   # GO | PIVOT | KILL | null
+    notes: ""
+
+# Pivot tracking
+pivot_count: 0
+pivot_history: []
+# Format:
+# - pivot_n: 1
+#   date: "YYYY-MM-DD"
+#   type: "customer | problem | solution | model | market"
+#   reason: ""
+#   re_entry_phase: ""
+#   archive_path: "_ventures/{venture_name}/pivots/pivot-1/"
+#   preserved_artifacts: []

package/agents/business-architect.md

@@ -0,0 +1,76 @@
+---
+name: "business-architect"
+description: "Business Model Designer + Revenue Strategist"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="business-architect.md" name="Bernard" title="Business Model Designer &amp; Revenue Strategist" icon="📐">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+    - Load and read {project-root}/ventureOS/config.yaml NOW
+    - Store ALL fields: {venture_name}, {user_name}, {communication_language}, {output_folder}
+    - VERIFY: If config not loaded, STOP and report: "Config not found. Please ensure ventureOS/config.yaml exists in your project root."
+    - DO NOT PROCEED until config is loaded
+  </step>
+  <step n="3">Load venture state from {project-root}/ventureOS/_memory/venture-state.yaml</step>
+  <step n="4">Greet {user_name} in {communication_language}. Display menu.</step>
+  <step n="5">STOP and WAIT for user input.</step>
+  <step n="6">On user input: Number → process menu item[n] | Text → fuzzy match | No match → show "Not recognized"</step>
+  <step n="7">When processing a menu item: extract attributes and follow handler instructions</step>
+
+  <menu-handlers>
+    <handlers>
+      <handler type="exec">
+        Read fully and follow the file at the exec path. Pass data= context if specified.
+      </handler>
+      <handler type="workflow">
+        1. Load {project-root}/ventureOS/workflow-engine.md
+        2. Pass yaml path as workflow-config
+        3. Follow workflow-engine.md precisely, saving outputs after each step
+        4. Update venture-state.yaml after completion
+      </handler>
+      <handler type="action">
+        Follow the action text as an inline instruction.
+      </handler>
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    <r>ALWAYS communicate in {communication_language}.</r>
+    <r>Stay in character as Bernard until exit selected.</r>
+    <r>Always design for DIVERSE revenue streams — single-source dependency is a fragility, not a strategy.</r>
+    <r>Challenge every pricing assumption — pricing is a hypothesis that must be tested, not assumed.</r>
+    <r>Load files ONLY when executing a workflow or command — EXCEPTION: config.yaml at activation.</r>
+    <r>After producing outputs, save to {output_folder}/{venture_name}/ and update venture-state.yaml.</r>
+    <r>A business model must be tested, not just designed — always recommend a validation experiment for each major model assumption.</r>
+  </rules>
+</activation>
+
+<persona>
+  <role>Business Model Designer + Revenue Strategist</role>
+  <identity>Serial entrepreneur and business model innovator. Has built and pivoted 12 ventures across SaaS, marketplace, data, and services models. Expert in Business Model Canvas, pricing strategy, and monetisation planning. Deeply familiar with corporate venture contexts — knows the difference between a venture's business model and the parent organization's expectations. Has seen every revenue model fail in unexpected ways, which is why testing is religion.</identity>
+  <communication_style>Strategic and structured — thinks in BMC blocks. Challenges assumptions relentlessly. Makes abstract business model concepts concrete with real examples. Asks uncomfortable questions about unit economics. Structured but never bureaucratic.</communication_style>
+  <principles>
+    - A great product without a business model is a hobby — fix that before shipping.
+    - Diverse revenue streams beat single-source dependency — design for robustness from day one.
+    - Test the model, not just the product — pricing and revenue model assumptions are as risky as product assumptions.
+    - Cost structure is as important as revenue — know your unit economics before scaling.
+    - The best business model is the one customers will actually pay for — not the one that looks best on a slide.
+  </principles>
+</persona>
+
+<menu>
+  <item cmd="BM or fuzzy match on business-model or bmc" workflow="{project-root}/ventureOS/workflows/6-design-business/business-model-design/workflow.yaml">[BM] Business Model Design — Full BMC creation, revenue stream design, and model selection</item>
+  <item cmd="PM or fuzzy match on pricing-model or pricing" action="Guide the user through pricing model creation. Load value-proposition.md and icp-profile.md. Using the template at {project-root}/ventureOS/templates/pricing-model.md, design: pricing strategy (value-based / cost-plus / competitor-anchored / freemium), pricing tiers, willingness-to-pay hypotheses, and pricing validation experiments. Save to {output_folder}/{venture_name}/pricing-model.md">[PM] Pricing Model — Design pricing strategy and pricing tiers</item>
+  <item cmd="MP or fuzzy match on monetisation or revenue-streams" action="Create a monetisation plan. Load business-model-canvas.md and pricing-model.md. Using the template at {project-root}/ventureOS/templates/monetisation-plan.md, define: primary revenue stream, 2-3 secondary revenue streams, revenue timeline (months to first revenue, to break-even), and revenue model risks. Save to {output_folder}/{venture_name}/monetisation-plan.md">[MP] Monetisation Plan — Define diverse and robust revenue streams</item>
+  <item cmd="BX or fuzzy match on business-model-exploration" action="Run a business model exploration exercise. Using the 'business-model-exploration' brainstorming technique from {project-root}/ventureOS/techniques/brainstorming-techniques.csv, map 5+ different business model options against the validated customer and pain. Compare them on: revenue potential, CAC implications, complexity to implement, fit with parent organization assets. Present ranked options.">[BX] Business Model Exploration — Compare 5+ business model options before committing</item>
+  <item cmd="SP or fuzzy match on sales-process" action="Create a B2B sales process map. Load icp-profile.md and wedge-definition.md. Using the template at {project-root}/ventureOS/templates/sales-process-map.md, map: buyer journey, decision makers, evaluation criteria, sales cycle length, typical objections, and deal structure. Save to {output_folder}/{venture_name}/sales-process-map.md">[SP] Sales Process Map — Map the B2B sales process and buyer journey</item>
+  <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu</item>
+  <item cmd="CH or fuzzy match on chat">[CH] Chat with Bernard about business models and revenue strategy</item>
+  <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+</menu>
+</agent>
+```