111k

Project Core Structure

Project architecture contract synced from the project module source documents.

Core Definition

Define the root object chain of project: outcome, workstream, task, activity, and assets.

Execution Architecture

Explain the main operating loop, five architecture planes, control plane, and execution unit chain.

Operating System

Define execution mode, runtime, commands, hooks, automation, continuity, and operating posture.

Version Spine

Explain how project change becomes versioned, reviewable, and promotable through git domains.

Surface Mapping

Map the architecture onto the current board UI, tabs, control plane, and execution projections.

Boundary & Version Strategy

Define what GitHub, Notion, Linear, and Cloudflare own, and where project-level version governance must begin.

Purpose

This document is the board home and architecture index for the project module.

It does not try to explain the whole project system in one uninterrupted essay.

Its job is to define:

  • what the toProject board is for
  • which blocks organize the board
  • which topics belong to each block
  • which pages define each part of the system
  • how the reader should move through the board

This page is the reader's map before the detailed docs begin.

Why This Exists

The project module reached a point where UI refinement alone was no longer enough.

We hit repeated structural drift:

  • Work items drifting toward timeline/gantt behavior
  • Timeline and Work items sharing rendering assumptions that should have stayed separate
  • Overview, Outcome, Workstream, Tasks, and Notes carrying overlapping meanings
  • Project itself behaving partly like a task container, partly like a document, and partly like a runtime panel

That made one thing clear:

The missing piece was not another visual pass.

The missing piece was a project-centered architecture contract.

That is why this index exists first.

If we start from isolated sub-documents without restating the argument, the architecture becomes mechanically structured but intellectually thin. The reader can see the folders and headings, but not the reasoning chain that forced the split.

Core Thesis

Project is the git-backed execution container of the agentic platform.

It is not:

  • only a runtime panel
  • only a task board
  • only a document surface
  • only a wrapper around an execution engine

It is the root coordination object that organizes:

  • outcome
  • workstream
  • task
  • activity
  • asset / file
  • timeline projection
  • runtime state

under an agent-led operating model.

This is the sentence that all other documents are meant to defend, refine, or implement.

Board Definition

toProject is a board, not just a folder of project docs.

As a board, it should do three things at once:

  • define the semantic center of project
  • explain how project executes
  • map that architecture onto the current product surface

That means the board needs internal structure.

The board is not one long article.

It is a system of:

  • board
  • block
  • topic
  • page

For toProject, those layers should be read like this:

  • board: toProject
  • block: one major architecture lane inside the board
  • topic: one bounded knowledge concern inside a block
  • page: the concrete document that explains that topic

Block Structure

The toProject board should be read through five blocks.

Use the cards above as the fast entry path.

Use the sections below as the detailed block map.

1. Core Definition

This block defines what project is.

It owns topics such as:

  • root object
  • outcome
  • workstream
  • task
  • activity
  • assets / files

Primary page:

2. Execution Architecture

This block defines how the whole project system operates as one execution architecture.

It owns topics such as:

  • main execution loop
  • five architecture planes
  • control plane
  • tab architecture
  • execution unit chain
  • failure modes

Primary page:

3. Operating System

This block defines runtime-facing execution behavior.

It owns topics such as:

  • execution mode
  • runtime
  • execution sandbox
  • actor model
  • capability model
  • runtime scheduling
  • commands and skills
  • hooks and automation
  • continuity
  • blocking and permission posture

Primary page:

4. Version Spine

This block defines how project change becomes versioned, reviewable, and promotable.

It owns topics such as:

  • project-level git role
  • spec domain
  • execution domain
  • knowledge domain
  • review boundary
  • deploy linkage

Primary page:

5. Surface Mapping

This block defines how the architecture is currently expressed in product UI.

It owns topics such as:

  • control plane fields
  • tab mapping
  • view projections
  • missing fields
  • transitional surfaces

Primary page:

6. Boundary & Version Strategy

This block defines why toProject exists alongside existing tools, what each external system owns, and how versions are governed across source, execution, and artifacts.

It owns topics such as:

  • why toProject exists
  • what GitHub owns
  • what Notion owns
  • what Linear owns
  • what Cloudflare owns
  • source version
  • execution version
  • artifact version
  • run ledger
  • artifact ledger
  • when GitHub is not enough

Primary page:

Topic Map

The board should be read as a topic map, not just as a doc list.

Core Definition Topics

  • Project Root
  • Outcome
  • Workstream
  • Task
  • Activity
  • Assets & Files

Execution Architecture Topics

  • Main Loop
  • Five Planes
  • Control Plane
  • Tab Architecture
  • Execution Unit Chain
  • Execution State Machine
  • Observability & Evaluation
  • Failure Modes
  • Implementation Priorities

Operating System Topics

  • Execution Mode
  • Runtime
  • Execution Sandbox
  • Actor Model
  • Capability Model
  • Runtime Scheduling
  • Commands
  • Skills
  • Hooks
  • Automation
  • Continuity
  • Activity As Operating Evidence

Version Spine Topics

  • Why Git Is Core
  • Spec Domain
  • Execution Domain
  • Knowledge Domain
  • Review Boundary
  • Project-Level Git Surface

Surface Mapping Topics

  • Overview Tab
  • Outcome Tab
  • Workstream Tab
  • Tasks Tab
  • Activity Tab
  • Assets & Files Tab
  • List / Board / Timeline Projections
  • Current Gaps

Boundary & Version Strategy Topics

  • Why toProject Exists
  • What GitHub Owns
  • What Notion Owns
  • What Linear Owns
  • What Cloudflare Owns
  • Version Management Strategy
  • Run Ledger
  • Artifact Ledger
  • When GitHub Is Not Enough

Document Structure

This architecture is intentionally split into focused documents to avoid one oversized, high-context page.

The split is not for its own sake.

We split because the architecture now has two different reading modes:

  • a reader trying to understand the whole project-centered thesis
  • a reader trying to answer one bounded question, such as git, runtime, or UI mapping

One document cannot do both well without becoming too long and expensive to read.

1. Index

2. Object Model

  • PROJECT_OBJECT_MODEL.md
  • Focus: what the project-centered object model is and why it exists
  • Reason it is separate: this is the semantic center of the system, and it needs uninterrupted narrative space

3. Git Model

  • PROJECT_GIT_MODEL.md
  • Focus: what git domains exist, why git is core, and how project binds to them conceptually
  • Reason it is separate: git is no longer a tooling footnote; it is part of the project architecture itself

4. Runtime Model

  • PROJECT_RUNTIME_MODEL.md
  • Focus: what the operating layer is, including runtime, execution mode, commands, hooks, automation, and continuity
  • Reason it is separate: runtime logic is essential, but if mixed into the object model it will overpower the project-centered thesis

5. Execution Architecture

  • PROJECT_EXECUTION_ARCHITECTURE.md
  • Focus: how intent, decomposition, runtime, git, and evidence combine into one operating loop
  • Reason it is separate: this is the synthesis doc that turns the individual definition docs into one readable execution system

6. UI Mapping

  • PROJECT_UI_MAPPING.md
  • Focus: how the current UI maps to the architecture, what is aligned, and what is still transitional
  • Reason it is separate: current implementation state should not dilute the definition docs

Reading Order

Recommended reading order:

  1. this document
  2. PROJECT_OBJECT_MODEL.md
  3. PROJECT_EXECUTION_ARCHITECTURE.md
  4. PROJECT_RUNTIME_MODEL.md
  5. PROJECT_GIT_MODEL.md
  6. PROJECT_UI_MAPPING.md

That order is intentional:

  • object model first, so the root semantics are stable
  • execution architecture second, so the reader sees how the parts combine
  • runtime and git next, so operating details are interpreted in context
  • UI mapping last, so implementation state does not distort definition

Suggested Paths

Use these reading paths depending on the question in front of you.

If the question is semantic

Read:

  1. Project Object Model
  2. Project Execution Architecture

If the question is operational

Read:

  1. Project Execution Architecture
  2. Project Runtime Model
  3. Project Git Model

If the question is implementation-facing

Read:

  1. Project Execution Architecture
  2. Project UI Mapping

Architecture Shape

The architecture is split into three levels:

1. Project-Centered Definition

This defines the root object and its subordinate object types.

Primary source:

  • PROJECT_OBJECT_MODEL.md

This level answers:

  • what is the root object
  • what belongs inside it
  • what semantic chain gives the module coherence

2. Operating Definition

This defines how the project is allowed to execute and how versioned execution is governed.

Primary sources:

  • PROJECT_GIT_MODEL.md
  • PROJECT_RUNTIME_MODEL.md
  • PROJECT_EXECUTION_ARCHITECTURE.md

This level answers:

  • how the project is versioned
  • how it is allowed to run
  • how those planes combine into one operating loop
  • how engines, commands, hooks, and continuity relate to project semantics

3. UI And Surface Mapping

This defines how the current implementation should express the architecture.

Primary source:

  • PROJECT_UI_MAPPING.md

This level answers:

  • where the current UI already expresses the architecture
  • where it is still using transitional placeholders

Reference Position

This architecture is informed by agentic platform engineering references such as the Saul Fernandez model, but it is not a direct copy.

We adopt principles, then extend them locally.

The most important adopted principles are:

  • agent intelligence must be treated as infrastructure
  • git is the backbone
  • intent, execution, and knowledge should be separated
  • execution requires explicit operating surfaces

The most important local extensions are:

  • Project as the primary product object
  • Outcome -> Workstream -> Task as the core structural chain
  • Activity as execution evidence
  • project-centered UI contracts
  • Cloudflare-only runtime assumptions

Current Direction

The current implementation direction should converge toward:

  • project as a git-backed execution container
  • Cloudflare as the runtime plane
  • outcome, workstream, task, activity, and assets as explicit object surfaces
  • overview as a summary surface, not a dumping ground
  • work items, board, and timeline as separate projections over the same execution model

In other words:

  • object semantics must stay stable
  • operating semantics must stay explicit
  • UI projections must stay subordinate to both

Non-Goals

  • putting the entire architecture into one endlessly growing page
  • collapsing project into runtime
  • collapsing project into task tracking
  • collapsing project into documentation only
  • collapsing project into a single execution engine

Board Home Use

This page should remain the board home.

It should always answer:

  • what toProject is for
  • which blocks exist
  • which topics belong to them
  • where a reader should go next

Next Docs

The next architecture documents should continue the same split:

  • definition docs answer what + why
  • implementation docs answer how

This split is required to keep doc.topoo.ai readable, composable, and low-context.

Execution Architecture Summary

The toProject board should be read as one operating system for delivery.

That means the board is not just where tasks are listed.

It is where five planes are made to work together:

  • intent
  • decomposition
  • operation
  • git versioning
  • evidence

The canonical chain is:

Project -> Outcome -> Workstream -> Task -> Activity / Assets

The operating loop is:

Intent -> Workstream -> Task -> Runtime -> Git -> Activity -> Updated Project State

That loop is what makes the board more than a planning tool.

It turns the board into the execution architecture of the product.