Project Runtime Model

Project architecture contract synced from the project module source documents.

Purpose

This document defines the what + why of the project operating layer.

It covers runtime-facing concerns that are necessary for agentic execution but should not replace the project object model.

It exists because once a project becomes agentic, static object definitions are no longer enough. Something must explain how those objects are allowed to run.

Block Position

Inside the toProject board, this page is the primary definition page of the Operating System block.

It primarily owns these topics:

Execution Mode
Runtime
Commands
Skills
Hooks
Automation
Continuity
Activity As Operating Evidence

This page explains the operating posture of project after the object model has already been defined.

Core Position

Project is not runtime.

Runtime is a facet of project.

Project defines and organizes the execution contract. Runtime expresses the current live operating state of that contract.

Both are required.

This distinction is easy to lose in agent-heavy systems, where runtime can become so visible that it starts to masquerade as the whole product.

What The Operating Layer Covers

The operating layer turns project structure into executable behavior.

It must explicitly cover:

execution mode
commands and skills
hooks and automation
session continuity
activity as operating evidence

This layer exists to answer a question the object model cannot answer by itself:

"Given this project structure, how is execution actually allowed to happen?"

Runtime Is Federated, Not Singular

The runtime should not be modeled as one machine or one service.

It should be modeled as a federation of execution environments.

In practice that means:

some execution happens on the local machine
some execution happens in managed cloud runtime
some execution happens on external or rented infrastructure
some execution may be triggered from edge devices or lightweight surfaces

This matters because the system is not designing around one host.

It is designing around one execution contract that can move across many hosts.

The Four Runtime Classes

The cleanest runtime split is:

1. Local Runtime

Examples:

local terminal
local worktree
local IDE
local dev server
local agent process

Best for:

code editing
repo-aware execution
fast iteration
high-trust local actions

2. Managed Runtime

Examples:

Cloudflare Workers
Cloudflare Queues
scheduled jobs
managed online APIs

Best for:

ingress
lightweight orchestration
public endpoints
event handling
online always-on services

3. External Runtime

Examples:

rented compute
remote containers
CI runners
remote execution nodes
third-party APIs

Best for:

heavy compute
isolated execution
scale-out work
provider-specific tools

4. Edge / Device Runtime

Examples:

phone
watch
tablet
browser extension
desktop companion surface

Best for:

notification
trigger
approval
status inspection
lightweight control

Trigger Surface And Execution Surface Are Not The Same

One of the most important runtime rules is:

The place where a run is triggered does not have to be the place where it executes.

Examples:

a user triggers from a watch, but execution runs in Cloudflare
a local UI triggers a run, but compute executes on a rented node
a webhook enters through Cloudflare, but execution continues on a repo-aware local runtime

This separation is necessary because trigger surfaces are about access and control, while execution surfaces are about capability and cost.

Runtime Federation Is Not Yet A Compute Cluster

The long-term direction may eventually include true compute scheduling across many nodes.

But the current architecture is not a giant compute cluster by itself.

It is first an execution control plane that can coordinate many runtimes.

That distinction matters.

Google-style large-scale compute systems solve:

low-level resource scheduling
cluster-wide allocation
fleet-scale execution balance

toProject solves a different layer first:

human + agent execution coordination
runtime selection
version linkage
artifact lineage
evidence trail

But Compute Scheduling Will Eventually Matter

Later, the runtime layer should grow a scheduling capability.

That scheduler should eventually answer:

which runtime class should take this run
whether the run needs local context or remote scale
whether the run should be routed to Cloudflare, local execution, or rented compute
how priority, cost, and urgency affect routing

This means compute scheduling is a later extension of runtime federation, not a replacement for it.

The system should be built so that scheduling can emerge naturally from the existing runtime model.

Execution Mode

Execution mode describes the operating policy under which the agent is allowed to act.

Examples:

plan
supervised execution
autonomous execution
paused / waiting

This is distinct from Status.

Status describes the work state. Execution Mode describes permission and operating posture.

This separation matters because projects can be active while execution is paused, or planning can still be active while direct execution is intentionally constrained.

Commands And Skills

Tasks alone are not enough to describe an agentic project.

The operating layer must also acknowledge reusable executable capabilities such as:

commands
skills
workflows
setup actions
review actions

These act on project state but are not the same thing as project objects.

That is why they belong here rather than in the object model doc. They are capabilities, not root semantics.

Hooks And Automation

An agentic project requires event-driven behavior.

This includes:

pre-execution hooks
post-execution hooks
review hooks
sync hooks
scheduled jobs / automation

These behaviors shape how activity is produced and how execution is governed.

Without them, the system looks interactive but not operationally explainable.

Session Continuity

Agentic execution is not a one-shot request/response system.

It requires continuity features such as:

session resume
context carry-forward
compaction / summarization
interruption recovery
diagnostic / doctor flows

This is where agentic systems differ from simple request/response products. Continuity is not a nice-to-have; it is part of the runtime contract.

Activity As Operating Evidence

Activity is not only a note stream.

It is operating evidence.

Activity may be generated by:

user actions
agent actions
git events
hooks
review / approval events
automation runs

This is why Activity remains a top-level object type in the project-centered model.

Activity sits at the seam between object model and operating layer. It is the record where runtime becomes inspectable.

Execution Engine Position

A Claude Code-like system belongs at the execution engine layer, not at the project root.

It is best understood as:

a code-domain execution engine
a repo-aware agent runtime
a command / tool / hook driven execution environment

Project owns the execution contract. The operating layer constrains execution behavior. The execution engine executes inside those constraints.

This separation is what lets us learn from Claude Code-like systems without letting them redefine the whole platform around one engine's affordances.

Boundary

This page does not define:

the root chain of project objects
the git version spine
the current UI tab implementation

Those belong to:

Relationship To The Rest Of The Architecture

This document defines runtime semantics conceptually.