naive-framework 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md: everything-ecosystem
+
+The map of this repo, loaded by every agent.
+
+## What this is
+
+The Everything Ecosystem methodology, packaged as one private repo (EE-001). Proposed genus: a venture development framework, in the same genus as web development frameworks (EE-024). Four layers (purpose, knowledge, operations, evidence) plus governance and interface. Knowledge is the memory layer where every record is stored, and the other layers define the records they write to it; SAD is no longer part of the system (EE-036). Operations is business operations (team, hiring, handoffs); execution folded into it, and MAD, the method for building software, left to be its own product (EE-038).
+
+## Where things are
+
+| Path | Holds |
+|---|---|
+| `purpose/` | Frameworks and skills for articulating why |
+| `knowledge/` | The memory layer: `layer.json`, storage `tooling/`, and two skills (`find-reference`, `industry-awareness`) |
+| `operations/` | Business operations: team-design, recruiting and tool-selection skills, handoff v2, founder operating model (EE-038) |
+| `evidence/` | `evals/`, design-documents registry, audit and review skills |
+| `governance/` | Company vault template, roles, decision rights, pillar skills |
+| `interface/` | Interfaces: the router (`router.mjs`) and the CLI, MCP server and HTTP API over it; the install skill; agent harnesses and the operator console |
+| `platform/` | The platform side (EE-041): connectors that reach a vendor (GitHub so far) and, later, hosting, integrations that call outside services and the template gallery. Everything else is framework; framework code never imports from here (`node schema/check-boundary.mjs`). See `platform/README.md` |
+| `site/` | Naive's docs and marketing pages: a Fumadocs site on Next.js, unpublished (EE-034, EE-080); see `site/AGENTS.md` |
+| `docs/reference/` | Generated reference: `ROUTES.md`, every route a venture has |
+| `docs/design/` | The ecosystem's own domain and systems design |
+
+## Build and test
+
+- `node test.mjs` runs every test and check below and reports each one; CI runs it on every pull request (`.github/workflows/test.yml`). It needs python3 with `jsonschema` for `schema/validate.py`.
+- `node evidence/skills/design-coverage/check.mjs --entity <dir>` checks design coverage for an entity.
+- `node schema/check-ventures.mjs <dir>`, `node schema/check-nouns.mjs`, `node schema/check-integrations.mjs` check the schema's cross-file rules.
+- `node schema/check-data-model.mjs` checks the data model and kit manifests (every JSON file has a record type, every skill one kit); `--md` prints the layer relationships derived from the kits (EE-018).
+- `node schema/check-ready.mjs <venture dir> <handoff id>` checks a handoff is ready before anyone executes it (EE-019); `--record --by <who>` records it.
+- `node schema/check-governance.mjs <dir>` checks ownership, boards, founder agreements and exits; `node schema/payouts.mjs <venture dir> [value]` computes who gets what in a sale (EE-022).
+- `node schema/check-telos.mjs <dir>` checks each venture's telos (start with the end: every phase exit criterion traces to a measure).
+- `node schema/check-publication.mjs <dir>` checks each venture's publication policy and every handoff that publishes: a named channel and content rule, and a person approving (EE-025).
+- `node schema/check-validation.mjs <dir> [--json]` grades each venture's validation records from their cited evidence (high to very low, adapted from GRADE). The validation package is `packages/validation/` (EE-071). A kit, Mentura's enhanced package, will live under `platform/kits/` and is not built yet.
+- `node schema/check-execution.mjs <venture dir>` checks handoffs, evidence and decision rights; `node schema/run-handoff.mjs <venture dir> <handoff id>` runs a handoff's done-criteria and writes evidence (EE-017).
+- `node interface/cli/naive.mjs typegen` writes `.naive/types/` from the route table and the MCP tools. `mentura typegen` is the same command. `naive upgrade <venture dir>` (was `mentura migrate`) moves a venture onto the next Naive layout. `naive port --from <project> --venture <dir>` plans bringing a project in with its files as they are, and `--apply --confirm port` carries the plan out, read-only on the project (EE-076, `node schema/port-test.mjs`). `naive migrate --from <project> --venture <dir>` has an agent rewrite the project as records, settled by `migrate-<function>` decisions and written through the router with `--apply` (`node schema/migrate-test.mjs`, with a stand-in agent). Neither opens a file that looks like a secret. `schema/init-venture.mjs` creates new ventures only. `node schema/check-private.mjs <dir>` fails when a private record or field could reach a model. `node schema/gate.mjs` is not a CLI: the gate reads `naive.config.json` and package gates and never calls a model.
+- `node interface/cli/mentura.mjs <route> <action> --venture <id>` reads, writes, checks or runs one route; `node interface/mcp/server.mjs` is the MCP server and `node interface/api/server.mjs` the local API, all over `interface/router.mjs` (EE-030). Routes follow the Next.js App Router (EE-032): `[id]` collection items, nested ventures by path, layout, view, not-found, loading and error, route groups by phase, the `system/overview` slots and team-plan robots; see `docs/reference/ROUTES.md`. `node interface/test.mjs` tests them. Records are read and written through connectors for the venture's sources (`knowledge/connectors/`, EE-037); `node knowledge/connectors/eval.mjs` runs the framework's (filesystem) and `node platform/connectors/eval.mjs` the platform's (GitHub), both against `knowledge/connectors/suite.mjs`. The source map's `rules` are the source-of-truth matrix (EE-042, `knowledge/connectors/resolve.mjs`): a system of record and owner per record type, attribute and context; `node schema/check-sources.mjs <dir>` refuses ties, and `node schema/check-where-used.mjs <dir>` reports where-used children that drifted from their parent. Every write through them appends to the venture's provenance log, `provenance.jsonl` (EE-031); `node schema/check-provenance.mjs <dir>` checks its hash chain, and `mentura baseline --venture <id>` adopts records written before the log. `node schema/need-now.mjs <venture dir>` says what a venture needs now (EE-028); `node schema/time-to-ready.mjs <venture dir>` measures time to running and ready; `node schema/check-team.mjs <dir>` checks team plans against the agent capability register (EE-029).
+- `node schema/assess-problem.mjs <venture dir> [--as-is]` (route `purpose/validation/assess`) says what the problem's evidence is strong enough for: four assumptions labelled demonstrated to contradicted, the commitment they support (explore, prototype, charge, raise) and the next test, with no single score; it asks first when the record is incomplete (EE-050). `node schema/foundation.mjs <dir>` (route `purpose/foundation`) reports the strategic foundation by the Five Ws and How plus whether, and whose each is; `mentura confirm <statement>` and `mentura accept` of a foundation record need the name typed (EE-051).
+- `node schema/bdd.mjs <file.feature>` runs Gherkin behaviors as tests, with step definitions in `<file>.steps.mjs`; behaviors are written first (EE-050).
+- `node purpose/frameworks/product-anatomy/test.mjs` tests the Product Anatomy runner's role rules.
+- `node schema/test.mjs` tests the checkers on broken copies; `python3 schema/validate.py` validates every record against its schema.
+
+## Rules
+
+- Never read or print `.env*` files.
+- Schema decisions are logged in `docs/decisions/decisions.json` and cited by id (`EE-NNN`). The schema never cites a decision from any instance.
+- Torian merges. Agents open draft PRs and do not merge.
+
+## Tooling
+
+Every layer has `<layer>/tooling/integrations.json`: the tools and services it can use, each checked against `schema/integration.schema.json` (status in-use, candidate or rejected; interfaces such as files, MCP, API, SDK; credentials by variable name only). Agent runtimes (Claude Agent SDK, Cursor Agent SDK) are listed under `execution/tooling/`. The interface layer is narrower: an interface lets a person, with agents, work across at least three of the five other layers in one session. Agent harnesses (Claude Code, Cursor, Codex) are the default kind; the operator console is a custom one. A tool serving one or two layers (Obsidian, Linear) is an integration of those layers. `node schema/check-integrations.mjs` enforces this.
+
+Choosing tools is opt-in: when someone wants help, `operations/skills/tool-selection/SKILL.md` gives the principles for the questions and the scoring (Jev plus a reasoning model), and each layer's `tooling/questions.md` gives its dimensions and example questions. Knowledge has one so far.
+
+## Ventures
+
+The ecosystem is a schema; a workspace is an instance made of ventures (EE-002, EE-011). A venture is anything a builder undertakes, at a phase from Discovery to Platform (EE-012); personal life is out of scope (EE-009). Each venture has a `venture.json` (`schema/venture.schema.json`), product cards in `products/`, account records in `accounts/` where it keeps them (EE-021), and the three pillars. Create one with `node schema/init-venture.mjs`; check a workspace with `node schema/check-ventures.mjs <dir>`. Work in a venture runs as handoffs (`execution/handoffs/`), proved by evidence (`evidence/results/`), under its decision rights (`governance/decision-rights.json`). The repo's own first venture is `instance/ventures/everything-ecosystem/`. Every record type is indexed in `schema/README.md` and listed, with its owning layer, in `schema/data-model.json`. Each layer's manifest (skills, records it still owns, reads and writes) is in `<layer>/layer.json`. Venture packages are `packages/<name>/package.json`. A kit is Mentura's enhanced package, at `platform/kits/`, and none are built yet (EE-071). See `docs/design/LAYERS_AND_KITS_2026-10-27.md`. Design: `docs/design/VENTURES_2026-10-27.md`.
+
+## Nouns and references
+
+Standards first (EE-014): use an established term with its standard meaning, and coin one only when none exists. `docs/ontology.json` is canonical for nouns (`docs/ontology.md` is its readable form); `node schema/check-nouns.mjs` fails when a retired noun reappears. Each layer keeps the sources behind its defaults in `<layer>/references/references.json`; `knowledge/skills/find-reference/` fills and re-checks them.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Torian Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# Everything Ecosystem
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**An AI-native venture development framework for builders.** One methodology for developing what a builder builds, from a hobby to a company, with AI agents, in four layers that form a loop, plus two that cut across them. It is a schema: a builder's workspace is an instance of it (EE-002). Private for now (G-035); which parts become public is decided later.
+
+| Layer | Question | Folder | Today |
+|---|---|---|---|
+| Purpose | Why | `purpose/` | Discovery frameworks (BASED goals), ambition tiers |
+| Knowledge | Memory: where every record is stored; the other layers define what they write here (EE-036) | `knowledge/` | storage tooling, the find-reference and industry-awareness skills |
+| Operations | How the business runs: team, hiring, handoffs of work to people and agents (EE-038), by department (EE-047) | `operations/` | Department catalog (APQC and the value chain), imported only when needed (EE-048); team design, recruiting and tool-selection skills; handoff v2; founder operating model. MAD, the method for building software, is a separate product |
+| Evidence | Did it work | `evidence/` | Evals, design-coverage registry and checks, metrics review |
+| Governance (cross-cutting) | Who may decide | `governance/` | Company vault template, roles, decision rights, pillar skills |
+| Interface (cross-cutting) | How you work across the layers at once | `interface/` | Agent harnesses (Claude Code, Cursor), operator console |
+
+`docs/design/` holds the ecosystem's own domain and systems design. Each layer has a `tooling/integrations.json` listing the tools it can plug into (Obsidian, Notion, Linear, the Claude and Cursor agent SDKs and so on), checked against `schema/integration.schema.json`. 
+The loop: Purpose is articulated into Knowledge, Operations hands the work to people and agents, and Evidence feeds back into Knowledge and Purpose.
+
+## What kind of thing it is
+
+A **venture development framework** (proposed genus, EE-024), in the same genus as web development frameworks. A web framework gives a developer conventions, a project structure, generators, a test runner and plug-in packages, and calls the developer's code. This one gives a builder the same for a venture:
+
+| Web development framework | Everything Ecosystem |
+|---|---|
+| Conventions over configuration | One opinionated default per choice, each with references (EE-014) |
+| Project structure | Workspace, venture folders, six layers, record types (`schema/data-model.json`) |
+| Generator (`rails new`) | `node schema/init-venture.mjs` |
+| Test suite | `node test.mjs`: every check, run in CI |
+| Packages and plug-ins | Venture packages (`packages/<name>/package.json`); a kit is Mentura's enhanced package (`platform/kits/`, EE-071) |
+| Inversion of control | The framework's checks and runners call on the venture's records |
+
+It replaces the earlier description "AI-Native OS for Builders": an operating system or operating model describes how one organization runs, while a framework is reused by many builders to build their own.
+
+## Framework and platform
+
+The system has two sides, the way Next.js and Vercel do (EE-041): the framework is **Naive** and the platform is **Mentura** (EE-043). The framework is the conventions: it works offline, with no account, and names no vendor. The platform hosts, connects and integrates: connectors that reach a vendor, integrations that call outside services, hosting and a template gallery. Both live in this repository. The platform is in `platform/`, and framework code never imports from it (`node schema/check-boundary.mjs`). See `platform/README.md`.
+
+## Vault and repo
+
+Docs as code (EE-005): this repo holds the method, its design docs, schemas, skills and templates. Each instance keeps its own notes and decisions in its own ventures. The schema's decisions are in `docs/decisions/decisions.json`, and `schema/README.md` indexes every record type.