Vision and plan

State: open/active · Genre: strategy

What we are building, why, where it ends up, and the order of the work. The rest of the corpus hangs off this page: product entities carry each product’s boundary, decisions carry the choices, milestones carry the work.

What we are building

A control plane for a software factory: the ontology, the structure, and the tooling that let people and agents build software together. The record of the work stays in plain files the project owns.

The product is Ontological. This repo is its first instance. The repo holds projects at several depths: solutions, products, apps, and packages. That is part of today’s problem. It is also the model of what the control plane must handle.

Name	What it is	Where
Ontological	The product: a control plane that adopts software projects and runs their development.	solutions/ontological/ — PR-0001-sdlc
sdlc	Ontological’s command surface: the sdlc <noun> <verb> CLI, the entity model, and the Claude Code plugin with its skills.	solutions/ontological/{cli,lib,skills}
SDF	Ontological’s operator app: a desktop app with a browser mode. It registers projects, shows their work, and runs bounded actions through the CLI.	solutions/ontological/desktop — D-0018-sdf-control-plane-app
Foreman	The engine: a domain-blind distributed work runner in one Rust binary. Ontological is one registered instance on it. A product of its own.	packages/rust/foreman — PR-FRMN-foreman
ontogen	The generator that turns one Rust definition into HTTP, IPC, and MCP transports and a typed TypeScript client. SDF’s contract comes from it.	sksizer/rust-ontogen — D-0017-ontogen-shared-codegen-convergence

Three smaller products came out of the engine work and serve it. Each has its own product entity.

Product	Answers
PR-DZTZ-graph-scheduler	What is runnable now?
PR-0002-intersect	Do two scopes overlap?
PR-FLWL-flowline	How is a workflow authored?

Not part of the product: the determined suite under solutions/determined/ is a neighbour that shares a few packages and the platform-token pattern. apps/ontological-legacy is a salvage source.

Three parts

Part	What it is	Today
Ontology	What a project is made of and how the parts relate. Eleven kinds. Principle, standard, decision, term, reference, product, driver, and capability describe the system. Task, milestone, and backlog carry the work. The why → what → verify chain (D-7F2M-why-what-verify-chain) links them.	Shipped; the roster is D-ORMG-data-model
Structure	Where things live, so one tool works on any project: entities under docs/planning/<kind>/, one sdlc.yaml per project, runtime state under .sdlc/, a worktree per run, git refs as the coordination store.	Shipped; D-0001-project-structure
Tooling	The sdlc CLI and its ops, the harness plugin and skills, the Foreman engine, the SDF app. Every capability is a deterministic operation first. An LLM sits only where judgment is needed (S-0004-sdlc-cli-llm-head-deterministic-tail).	CLI, plugin, SDF shipped; engine in progress

The ontology is opinionated on purpose. A project takes it as it is, trims it, or extends it with kinds of its own.

The module graph

A software factory is not one flat project. It is a graph of modules: repos, solutions, products, apps, packages, crates, skill packs. Each module has a boundary. The control plane treats every module the same way.

Property	What it means
Its own internal model	A control unit carries its own decisions, capabilities, standards, and work, in its own structure. Nothing forces its entities into a parent’s corpus.
One node from outside	To the module around it, and to the control plane, a module is one node: a summary, the surfaces it publishes (S-0008-apps-consume-substrate-through-published-surfaces), the capabilities it claims, and its relations (contains, depends on, consumes). Rollups of status, readiness, and drift derive from members. You drill in to see the internal model.
Nesting to any depth, across repos	This repo → solutions/ontological → desktop is one path through the graph. A peer repo is another. Cross-module links are qualified ids (D-SK9G-cross-project-addressing). A repo can hold more than one planning root.

Structure and control are two dimensions

The graph has two layers, and they do not have to line up.

Layer	What it is	How it is set
Structure	Every code module and its relationships: packages, crates, apps, and the systems they touch.	Derived from manifests and code. Always visible, never declared by hand.
Control	Which part of the structure is managed as one thing. A control unit has one planning directory — its internal model — and one outside view.	Chosen. Declared as a planning root.

A control unit can be smaller than the structure suggests: a package with several code modules inside is one unit, planned once, with the relationships between those modules still visible. It can also be larger: a suite such as the markdown ecosystem — several packages and apps — is one unit with one planning directory (DR-6CO5). The rules:

• Every code module belongs to exactly one control unit.
• Structural edges may cross control boundaries; rollups follow control units.
• Moving a boundary is a declaration change, not a code move.

The graph is the first thing to build on the current base. Everything after it assumes it: multi-repo dispatch, SDF’s structural views, and publishing the definition half. The staged sequence is tracked in RM-0RYV and explained in N-PR1Z-ontological-control-plane-plan.

SDF draws it first. The first slice is read-only: the graph of this repo’s modules, a module’s outside view (summary, surfaces, capabilities, relations, rollups), and a drill-down into its internal model. Planning happens in our own tool from that point on (DR-F2QX).

Where it can be changed

The product is adapted at named places, not forked.

Kind	What it means	Where it exists
Modularity points	Swap an implementation behind a contract.	Engine ports: coordination backplane, run records, work-order source, runner context, agent driver (D-VSLI-distributed-work-runner-architecture). Harness adapters: one definition, many hosts (D-HRNS-harness-model-and-exporters). Transports: HTTP, IPC, and MCP from one definition. Entity kinds as registered packs. Definition and execution as separate packages (D-ME8T-definition-and-execution-packages).
Hook points	Run a project’s own code at a known moment.	Verbs in sdlc.yaml (setup, check, …) and per-repo trust (D-V2XJ-verb-cascade-and-repo-trust). Gates on commit and on quality runs. Process registrations in the engine. Bounded, token-guarded actions in SDF.
Opinionated defaults	What a project gets out of the box.	The starting ontology. The task lifecycle from idea to merged code through named operations (C-0001). Markdown and frontmatter on disk. Git refs for coordination. A worktree per run. A human on the merge.

Why it exists

The north star: create lots of high-quality software, faster than by hand and with more rigor than willpower alone can sustain.

Running a project through an agent harness today takes a lot of toil and keeps little memory.

Problem	Driver
The loop stalls without a human at every junction.	DR-0001
Capability is scattered across ad-hoc scripts with no discoverable surface.	DR-0002
Parallel branches and agents collide on ids and uncoordinated claims.	DR-0003
Nothing connects a unit of work to why it exists or how it is proven done.	DR-0004
The record of the work is trapped in whatever tool created it.	DR-0010

A large system is also too big to hold in one head. It exists at several levels — repo, solution, package, module — with many dependencies between them, and its work is shared between people and agents who each see only part of it. Without a boundary to reason inside, a person cannot tell what a change touches, and an agent cannot be handed a bounded piece of work (DR-8JAH). Control units chunk the system into pieces small enough to understand, each with its own model, so people and agents coordinate by unit and the whole stays legible from the top.

Ontological’s answer is to make a project legible, chunked, operable, and self-driving on a substrate that outlives its tools.

The bets

Bet	What it means	Anchors
Legible, long-lived substrate	Plain files that a human reads and git versions outlast any database or harness.	P-0007-long-lived-data-formats, P-0008-harness-agnostic-substrate
Deterministic where it has hardened	An LLM interprets freeform input at the edge. The effect underneath is structured, testable, and LLM-free, so the same capability runs from a shell, CI, or an agent session.	P-0001-prefer-deterministic-over-llm, S-0004-sdlc-cli-llm-head-deterministic-tail
Operationalize the work	Every activity is an invokable operation that emits structured state, so the project can act on its own signals.	P-0002-operationalize-activity, P-0010-capture-aggregate-act-on-signals
Self-hosting	Ontological is its own first user. Every improvement to the model improves how the project runs itself.	DR-0009, P-0006-self-hosting-development

The end state

Today’s Claude-Code-hosted shape is the starting point, not the destination (P-0003-pragmatic-architecture). At the end:

• Work is described once, as entities in the project’s own repo, and run by an engine that does not know the domain.
• Workflows are deterministic. An LLM is a bounded step inside one. The substrate is provider-agnostic; local or open models drive it where they are good enough.
• Coordination runs over a pluggable backplane. By default there is no server: git refs on one machine, or several peers sharing one ref authority. Later, an always-on server is one more peer, and an embedded store, Redis, or Postgres can sit behind the same coordination port. The corpus is never behind a port (DR-M4WK).
• The operator sees and steers everything from SDF: a local app over the engine’s status API and the CLI. Actions are bounded and token-guarded. The module graph is SDF’s map: every project, module, and rollup is reached from it.
• Any repo can be adopted. A project registers, is set up with one action, and runs, whether it lives in this monorepo or not. Several repos work as one roster, and the module graph is the map of all of them (DR-7TVN).
• The definition half of the ontology ships on its own as a library, a context pack, and a sdlc-def CLI. That half is principles, standards, decisions, terms, references, products, drivers, and capabilities. A project can take the model without the execution machinery (DR-2XPB).
• Every agent run is isolated in its own worktree (D-WK7T-agent-git-writes-worktree-isolated). A sandboxed runner is a later runner-context implementation.

The scheduler and the secure execution environment

Foreman is what runs the work. It is domain-blind: it does not know what a task or a milestone is. Ontological hands it work orders through a source port and registers the processes that run them.

Concern	What Foreman does	Where decided
Schedule	The graph-scheduler frontier says what is runnable now; a policy filter chain (scope conflicts via intersect, concurrency limits, readiness) narrows it.	PR-DZTZ-graph-scheduler, PR-0002-intersect
Claim	A run is claimed over the backplane with a lease, fenced so two peers never hold one order.	D-VSLI-distributed-work-runner-architecture
Execute	Registered processes: a command, a child process speaking the step protocol, or an agent through a registered driver; the run is journaled and resumable.	D-VSLI-distributed-work-runner-architecture
Contain	Every run is isolated: its own worktree today; the runner-context port is where a sandbox goes — deny-by-default egress, bounded resources, an event feed the operator can watch and amend (the cage patterns).	D-WK7T-agent-git-writes-worktree-isolated, DR-EJHU
Observe	A status API and event stream that SDF renders.	D-0018-sdf-control-plane-app

An agent given a bounded order in a bounded environment can be trusted with more, which is how the human gate moves from every step to the merge — and, for the gated class, past it.

The depth lives in PR-FRMN-foreman and D-VSLI-distributed-work-runner-architecture; this page only fixes what the engine is for.

What good looks like

Outcome	What it means	Anchors
Hands-off forward motion	One command keeps a project converging overnight and surfaces only what needs a human.	DR-0005
A smooth path from idea to merged code	A thought captured in one line becomes a tracked, executed, closed-out unit of work.	DR-0006, DR-0007
Traceable work	Every task walks up to a driver and down to the criterion that proves it.	DR-0004, D-7F2M-why-what-verify-chain
A durable record	The history stays readable and portable across whatever harness comes next.	DR-0010
Adoption in minutes	A new repo runs under Ontological after one setup action and shows up in SDF beside the others.	—
A system you can hold	From the top, the graph is a handful of units; inside each, the model is complete. Handing an agent a unit is handing it a boundary.	DR-8JAH, DR-6CO5

Non-goals and settled tensions

Line	Where it stands
No database of record.	Markdown on disk is the record; every other store is a view. The backplane is pluggable now. The record may become pluggable later, but nothing is built for that until a consumer needs it.
Humans merge.	The loop shepherds and a person merges. The exception is a bounded class of work that is deterministic and fully gated: generated-doc refreshes, dependency bumps, and system duties whose checks are complete. That class is declared per task kind, starts empty, and grows only as gates prove out (DR-VC8R).
No hosted control plane as a requirement.	A server is an optional peer, never the only way to run.
Not a general agent framework.	The engine is domain-blind, but the product is about software projects.

The plan

Milestones carry the work. This section gives the order and the reason for it.

Done

Milestone	Delivered
M-XVOC	sdlc ships as one binary per platform (D-2APS-sdlc-standalone-binary-app).
M-5EEX	SDF: scaffold, active-work view, legacy dashboard removed, ontogen transports, read panels, safe controls (D-0018-sdf-control-plane-app).
M-DZEM	SDF adopts any registered project: no ambient project, one-click sdlc setup with a dry-run preview.
RM-E2L0	The sdlc 0.8 campaign: v0.4.0, v0.7.0, and v0.8.0 tagged on sksizer/sdlc. Carry-over is listed in RM-0RYV; the audit is N-RH55-sdlc-0-8-release-reconciliation.
—	The two-plane split is cut over: the corpus is semantic and execution state lives in refs (D-S30G-task-state-plane-split). Schema v6 retires the old status values later.
—	Engine contracts, the foreman and graph-scheduler crate scaffolds, and the Rust intersect peer. The ledger is d-vsli-implementation-plan.md.

Next, in order

#	Phase	Milestones	Depends on	Outcome
1	Module graph, in SDF first	D-XCXA-module-graph, M-D2I1	M-ZLTF for control units; structure ships first	SDF shows the graph of this repo’s own levels. The read-only structural graph can ship first; control-unit views, drill-down, and rollups follow the planning-roots work.
2	Cross-project addressing	M-ZLTF	—	A task in another repo can be named, resolved, and audited; a repo holds more than one planning root.
3	Foreman lands	M-E1YP	—	The Foreman stack and ledger match; the product is settled; remote authority works across machines.
4	Definition kinds compose	M-3RZH	—	Every kind describes itself; every roster derives from the packs. Nothing moves yet.
5	sdlc on foreman	M-KBH8	3	The corpus is a work-order source; one real task goes from ready to an open PR through foreman run --once; the first lifecycle skill shrinks to a head.
6	Definition package publishes	M-XS4P	4	Four packages; @sksizer/sdlc-definition ships from the same tag; a consumer installs it alone.
7	Multi-repo dispatch	M-T5GN	2, 5	Work is picked and run across the roster’s peers.

Later planning inputs

• Simplify the task lifecycle: collapse the status enum, prune frontmatter, and move every procedural step into a verb. Prose stays only at judgment nodes.
• SDF over the engine: run and order panels on the status API and event stream.
• Publish the general skills to a marketplace, so any project gets them without the entity model (M-TDOH).
• Backplane beyond git: remote authority sync, then a server peer and store backends behind the coordination port.
• The auto-merge class: declare it per task kind once the gates exist.
• Consume a definition corpus from npm across repos.

The module-graph decision and milestone already exist (D-XCXA-module-graph, M-D2I1); the structural slice can proceed before the planning-root dependency M-ZLTF.

Words that mean one thing

Word	Meaning here	Not
Control plane	Ontological as deployed: the thing that adopts projects and runs their work.	The SDF app alone; an agent host such as Claude Code; a hosted server.
Module	A node in the structural graph: a repo, solution, product, app, package, crate, or skill pack, with the relationships derived from its manifests.	A file, or a directory with no model of its own.
Control unit	A chosen set of modules managed as one thing: one planning directory, one outside view, one set of rollups.	A directory with no planning root of its own.
Harness	An agent runner that consumes the substrate. Claude Code today. The skills layer is the harness adapter.	The engine; the operator app.
Backplane	The coordination layer the CLI and the engine claim and record through. Git refs today.	The corpus.
Engine	Foreman: the domain-blind work runner.	The sdlc CLI.
Work order	A unit of work handed to the engine through the source port; for Ontological, a task.	The task file itself.
Run	One execution of a work order by a registered process, claimed under a lease, journaled, isolated.	A shell session.
Ontological	The product.	The legacy app under apps/ontological-legacy, or the sibling repo it came from.

The glossary carries these once their term entities land.

Where older docs disagree

This page wins. Read the older lines as follows until they are rewritten.

Doc	Says	Read as
D-VSLI-distributed-work-runner-architecture	”SDLC is a distributed work runner”	Foreman is the work runner; Ontological is its primary registered instance.
D-VSLI-distributed-work-runner-architecture	”sdlc ships as one JS npm artifact”	It ships as a binary per platform (D-2APS-sdlc-standalone-binary-app).
D-0001-project-structure	SDLC “lives at apps/sdlc/”	It lives at solutions/ontological/, as the decision’s own end state says.
Older docs	”Dark Factory”	The software factory. The Python DarkFactory is a design reference only.
Older docs	”the SDLC product”, or “SDLC” as the project’s name	Ontological, the product; sdlc, its CLI and plugin.

Where to go next

• PR-0001-sdlc — the product: boundary, model, capability map.
• Drivers — the problems the product exists to solve.
• index — every entity, and the milestones in build order.

---

← Back to Notes