naive-framework 0.0.0-stage → 0.2.0

package/schema/validation-solution.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "validation-solution.schema.json",
+  "title": "Validation: solution",
+  "description": "The solution sub-score (EE-026), at <venture>/purpose/validation/solution.json: how the venture solves the problem, what people use instead, and cited evidence that people in the segment choose it over their current way.",
+  "type": "object",
+  "required": [
+    "venture",
+    "statement",
+    "alternatives",
+    "evidence"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "venture": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "statement": {
+      "type": "string",
+      "description": "How it solves the problem, in one or two sentences"
+    },
+    "product": {
+      "type": "string",
+      "description": "Product id, if one product carries the solution"
+    },
+    "alternatives": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "What people use instead today, including doing nothing"
+    },
+    "difference": {
+      "type": "string",
+      "description": "Why someone would switch"
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "$ref": "validation-evidence.schema.json"
+      }
+    },
+    "probability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "p",
+        "by",
+        "scored"
+      ],
+      "description": "The Jev probability for this sub-score; the evidence grade weighs it in the validation score",
+      "properties": {
+        "p": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "by": {
+          "enum": [
+            "jev",
+            "owner"
+          ]
+        },
+        "scored": {
+          "type": "string",
+          "format": "date"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/validation-team.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "validation-team.schema.json",
+  "title": "Validation: team",
+  "description": "The team sub-score (EE-026), at <venture>/purpose/validation/team.json: the skills the coming phases need, the skills held and by whom, and the gaps, including whether a cofounder is sought for them. schema/check-validation.mjs lists the gaps.",
+  "type": "object",
+  "required": [
+    "venture",
+    "needed",
+    "held",
+    "evidence"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "venture": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "needed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "skill",
+          "by_phase"
+        ],
+        "properties": {
+          "skill": {
+            "type": "string"
+          },
+          "by_phase": {
+            "enum": [
+              "discovery",
+              "validation",
+              "beachhead",
+              "scale",
+              "platform"
+            ]
+          },
+          "why": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "held": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "skill",
+          "by"
+        ],
+        "properties": {
+          "skill": {
+            "type": "string"
+          },
+          "by": {
+            "type": "string",
+            "description": "A role id, or 'agent:<role>' when an agent holds it"
+          }
+        }
+      }
+    },
+    "cofounder_sought": {
+      "type": "boolean"
+    },
+    "cofounder_skills": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "$ref": "validation-evidence.schema.json"
+      }
+    },
+    "probability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "p",
+        "by",
+        "scored"
+      ],
+      "description": "The Jev probability for this sub-score; the evidence grade weighs it in the validation score",
+      "properties": {
+        "p": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "by": {
+          "enum": [
+            "jev",
+            "owner"
+          ]
+        },
+        "scored": {
+          "type": "string",
+          "format": "date"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/venture-role.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "venture-role.schema.json",
+  "title": "Venture roles",
+  "description": "The roles a person can hold in a venture (governance/venture-template/roles/venture-roles.json), as distinct from the agent roles beside it. create-venture asks for one; people/people.json records who holds which.",
+  "type": "object",
+  "required": [
+    "version",
+    "roles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "kind",
+          "description",
+          "founder",
+          "owns_when_solo"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "name": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "builder",
+              "investor",
+              "operator",
+              "advisor",
+              "governor"
+            ]
+          },
+          "description": {
+            "type": "string"
+          },
+          "founder": {
+            "type": "boolean",
+            "description": "Whether the holder is a founder of this venture, with a file in people/founders/ and a place in the founder agreement"
+          },
+          "owns_when_solo": {
+            "type": "boolean",
+            "description": "Whether a person alone in this role owns every function the venture imports"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/venture-type.mjs

@@ -0,0 +1,62 @@
+// Venture types (EE-082): the registry, and a classifier that reads a founder's few words and says
+// which type the venture is. The classifier asks Jev one yes-or-no question per type (Noul) and ranks
+// the answers; below the threshold it is uncertain, and the founder picks from the list instead. Without
+// TYPESAFE_API_KEY there is no model call at all: the list is the way to choose.
+//
+//   node schema/venture-type.mjs list
+//   node schema/venture-type.mjs classify "<a few words about the venture>"
+//
+// MENTURA_TYPE_CMD replaces the call to platform/integrations/jev.mjs (it reads the request on stdin and
+// prints {answers}), for tests.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repo = new URL("..", import.meta.url).pathname;
+export const THRESHOLD = 0.5;
+
+export function types() {
+  return JSON.parse(readFileSync(join(repo, "schema/venture-types.json"), "utf8")).types;
+}
+export const typeOf = (id) => types().find((t) => t.id === id) ?? null;
+
+export function roles() {
+  return JSON.parse(readFileSync(join(repo, "governance/venture-template/roles/venture-roles.json"), "utf8")).roles;
+}
+
+/** Whether a model can classify: a TypeSafe key, or a stand-in command. */
+export const canClassify = () => Boolean(process.env.MENTURA_TYPE_CMD || process.env.TYPESAFE_API_KEY || process.env.TYPESAFEAI_API_KEY);
+
+/** The typed request: for each type, is the venture described this kind of venture? */
+export function request(description) {
+  const ts = types();
+  const questions = Object.fromEntries(ts.map((t) => [`type:${t.id}`, {
+    type: "noul",
+    instructions: `Is the venture described in \`venture.description\` a ${t.label.toLowerCase()} (${t.description} Founders call it things like: ${t.examples.join(", ")})?`,
+    criteria: { true: `Yes: it is mainly a ${t.label.toLowerCase()}`, false: "No: it is mainly something else" },
+  }]));
+  return { state: { venture: { description } }, model: "jev-latest", questions };
+}
+
+/** Ranked types for a description, most likely first, with uncertain set when none reaches the threshold. */
+export function classify(description) {
+  const cmd = process.env.MENTURA_TYPE_CMD ? process.env.MENTURA_TYPE_CMD.split(" ") : ["node", join(repo, "platform/integrations/jev.mjs")];
+  const p = spawnSync(cmd[0], cmd.slice(1), { input: JSON.stringify(request(description)), encoding: "utf8", env: process.env });
+  if (p.status !== 0) throw new Error(`the type classifier stopped: ${(p.stderr || p.stdout).trim().slice(0, 300)}`);
+  const { answers = {}, model = null } = JSON.parse(p.stdout);
+  const ranked = types().map((t) => {
+    const a = answers[`type:${t.id}`]?.noul;
+    return { id: t.id, label: t.label, p: typeof a === "number" ? a : a === true ? 1 : 0 };
+  }).sort((a, b) => b.p - a.p);
+  return { model, ranked, best: ranked[0].p >= THRESHOLD ? ranked[0] : null, uncertain: ranked[0].p < THRESHOLD };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const [cmd, ...words] = process.argv.slice(2);
+  if (cmd === "list") for (const t of types()) console.log(`${t.id.padEnd(18)} ${t.label}: ${t.description}`);
+  else if (cmd === "classify" && words.length) {
+    try { console.log(JSON.stringify(classify(words.join(" ")), null, 2)); } catch (e) { console.error(e.message); process.exit(1); }
+  } else { console.error('usage: node schema/venture-type.mjs list | classify "<a few words>"'); process.exit(2); }
+}

package/schema/venture-types.json

@@ -0,0 +1,346 @@
+{
+  "version": "0.1.0",
+  "note": "Venture types create-venture scaffolds (EE-082). The type decides the starting packages, first decisions, imported functions and the roles a person can hold. Start from a list, or describe the venture and let a model choose.",
+  "types": [
+    {
+      "id": "software-startup",
+      "label": "Software startup",
+      "description": "A company building a software product: an app, a SaaS, a developer tool or an AI product.",
+      "examples": [
+        "SaaS",
+        "app",
+        "startup",
+        "developer tool",
+        "AI product",
+        "platform",
+        "marketplace"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor",
+        "board-member"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "products",
+        "marketing-and-sales",
+        "customer-service",
+        "human-capital",
+        "it",
+        "finance"
+      ],
+      "packages": [
+        "foundation",
+        "validation",
+        "product",
+        "marketing",
+        "finance",
+        "people",
+        "customers",
+        "investors",
+        "money"
+      ],
+      "decisions": "product-foundation"
+    },
+    {
+      "id": "vc-fund",
+      "label": "VC fund or firm",
+      "description": "An investment fund or firm that raises from limited partners and invests in companies: a thesis, fund terms, a deal pipeline and a portfolio.",
+      "examples": [
+        "venture fund",
+        "VC firm",
+        "angel syndicate",
+        "seed fund",
+        "micro VC",
+        "rolling fund",
+        "investment firm"
+      ],
+      "roles": [
+        "general-partner",
+        "limited-partner",
+        "operator",
+        "advisor",
+        "board-member"
+      ],
+      "default_role": "general-partner",
+      "departments": [
+        "strategy",
+        "finance",
+        "external-relationships",
+        "risk-and-compliance",
+        "human-capital"
+      ],
+      "packages": [
+        "foundation",
+        "fund",
+        "deals",
+        "portfolio",
+        "investors",
+        "people",
+        "finance",
+        "money"
+      ],
+      "decisions": "fund-foundation",
+      "funding": "mixed",
+      "layers": [
+        "purpose",
+        "knowledge",
+        "governance"
+      ]
+    },
+    {
+      "id": "services-business",
+      "label": "Services business",
+      "description": "A business selling expertise or labor: an agency, consultancy, studio or freelance practice.",
+      "examples": [
+        "agency",
+        "consultancy",
+        "studio",
+        "freelance",
+        "professional services"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "service-delivery",
+        "marketing-and-sales",
+        "customer-service",
+        "finance"
+      ],
+      "packages": [
+        "foundation",
+        "validation",
+        "product",
+        "marketing",
+        "finance",
+        "people",
+        "customers",
+        "money"
+      ],
+      "decisions": "product-foundation"
+    },
+    {
+      "id": "local-business",
+      "label": "Local business",
+      "description": "A business serving customers in one place: a cafe, a shop, a clinic, a gym or a trade.",
+      "examples": [
+        "cafe",
+        "restaurant",
+        "shop",
+        "clinic",
+        "gym",
+        "salon",
+        "trade"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "service-delivery",
+        "marketing-and-sales",
+        "customer-service",
+        "supply-chain",
+        "finance",
+        "assets"
+      ],
+      "packages": [
+        "foundation",
+        "validation",
+        "product",
+        "marketing",
+        "finance",
+        "people",
+        "customers",
+        "money"
+      ],
+      "decisions": "product-foundation"
+    },
+    {
+      "id": "ecommerce",
+      "label": "E-commerce or physical product",
+      "description": "A business making or selling physical goods, online or wholesale.",
+      "examples": [
+        "e-commerce",
+        "online store",
+        "DTC brand",
+        "hardware",
+        "consumer product"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor",
+        "board-member"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "products",
+        "marketing-and-sales",
+        "supply-chain",
+        "customer-service",
+        "finance"
+      ],
+      "packages": [
+        "foundation",
+        "validation",
+        "product",
+        "marketing",
+        "finance",
+        "people",
+        "customers",
+        "investors",
+        "money"
+      ],
+      "decisions": "product-foundation"
+    },
+    {
+      "id": "creator-media",
+      "label": "Creator or media",
+      "description": "A venture built on content and an audience: a newsletter, channel, podcast or publication.",
+      "examples": [
+        "newsletter",
+        "YouTube channel",
+        "podcast",
+        "publication",
+        "creator"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "products",
+        "marketing-and-sales",
+        "finance"
+      ],
+      "packages": [
+        "foundation",
+        "validation",
+        "product",
+        "marketing",
+        "finance",
+        "people",
+        "customers",
+        "money"
+      ],
+      "decisions": "product-foundation"
+    },
+    {
+      "id": "nonprofit",
+      "label": "Nonprofit",
+      "description": "A mission-driven organization funded by donations and grants rather than profit.",
+      "examples": [
+        "nonprofit",
+        "charity",
+        "foundation",
+        "NGO",
+        "community organization"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor",
+        "board-member"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "service-delivery",
+        "external-relationships",
+        "finance",
+        "risk-and-compliance"
+      ],
+      "packages": [
+        "foundation",
+        "validation",
+        "product",
+        "marketing",
+        "finance",
+        "people",
+        "money"
+      ],
+      "decisions": "product-foundation",
+      "funding": "grant"
+    },
+    {
+      "id": "holding-company",
+      "label": "Holding company",
+      "description": "A company that owns and governs other ventures; each one it holds is a nested venture.",
+      "examples": [
+        "holding company",
+        "venture studio",
+        "parent company",
+        "portfolio of businesses"
+      ],
+      "roles": [
+        "founder",
+        "co-founder",
+        "operator",
+        "advisor",
+        "board-member"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "finance",
+        "risk-and-compliance",
+        "human-capital"
+      ],
+      "packages": [
+        "foundation",
+        "portfolio",
+        "finance",
+        "people",
+        "investors",
+        "money"
+      ],
+      "decisions": "none"
+    },
+    {
+      "id": "side-project",
+      "label": "Side project",
+      "description": "Something you build for its own sake, with no plan to make it a business yet.",
+      "examples": [
+        "side project",
+        "hobby",
+        "experiment",
+        "open source project"
+      ],
+      "roles": [
+        "founder",
+        "co-founder"
+      ],
+      "default_role": "founder",
+      "departments": [
+        "strategy",
+        "products"
+      ],
+      "packages": [
+        "foundation",
+        "product"
+      ],
+      "decisions": "product-foundation"
+    }
+  ]
+}