OpenWork Project Structure: A Complete Guide to the Monorepo Architecture

OpenWork is organized as a pnpm workspace monorepo with distinct directories for applications (apps/), shared libraries (packages/), end-to-end tests (evals/), and configuration files that integrate TurboRepo, Warden security scanning, and OpenCode skill registries.

The openwork project structure follows a modular monorepo pattern that consolidates a desktop Electron client, a cloud control plane (Den), reusable skills, and plugins into a single cohesive repository. Built as a pnpm workspace, the codebase enforces strict separation between runnable applications, shared TypeScript packages, documentation, and infrastructure tooling. This architecture enables rapid iteration across multiple targets while maintaining consistent build pipelines and security policies.

Top-Level Directory Layout

The repository root contains eight primary directories that define the project boundaries, alongside specialized configuration folders for development environments and security policies.

Path	Purpose
apps/	Runnable applications including the Electron desktop client and the Den web control plane
packages/	Reusable TypeScript libraries shared across apps (UI components, state stores, API clients)
evals/	End-to-end test suites and fraimz proof-of-concept scripts that drive the UI via CDP
scripts/	CI helpers, publishing automation, and repo maintenance utilities
docs/	Public documentation and Markdown guides powering the OpenWork website
examples/	Reference projects demonstrating how to embed OpenWork skills (e.g., Rust sandbox)
.devcontainer/	VS Code DevContainer definition for consistent development environments
.github/	GitHub Actions workflows, issue templates, and CI configuration

Specialized configuration directories include .opencode/ for skill registries and MCP definitions, .warden/ for security-review skill definitions, and patches/ for Yarn/PNPM patches that modify third-party dependencies without forking.

Applications and Packages

The apps/ directory houses the two primary entry points, while packages/ contains the shared logic consumed by both.

Desktop and Den Applications

• apps/desktop/ – The Electron-based desktop client containing the main process, preload scripts, and renderer UI. This package imports components from packages/ui and state management from packages/store.
• apps/den/ – The web-based cloud control plane and API gateway that manages remote skill execution.

Shared Libraries

The packages/ directory hosts reusable TypeScript libraries including:

• packages/ui/ – A shared React component library based on shadcn/ui, providing consistent design tokens across the desktop and web interfaces
• packages/store/ – Centralized state management utilities used by both applications
• Core API clients and utility functions that abstract platform-specific operations

New components are scaffolded under packages/ui/ and imported using workspace aliases:

import { Button } from '@openwork/ui/button';

Configuration and Workspace Management

The openwork project structure relies on four critical root-level configuration files to orchestrate builds, dependencies, and security policies.

Workspace Definition (pnpm-workspace.yaml)

This file lists every folder containing a package.json, enabling pnpm to hoist shared dependencies and run commands across the entire repository:

# Install all workspace dependencies

pnpm install

# Start the default development profile (desktop + Vite dev server)

pnpm dev

The pnpm dev command prints a banner indicating the CDP debugging endpoint: [openwork] dev profile=default cdp=http://127.0.0.1:9223.

Build Orchestration (turbo.json)

TurboRepo pipelines defined in turbo.json manage the dependency graph between install, build, and test tasks. This configuration ensures only packages with changes are rebuilt, dramatically accelerating CI cycles.

Security Policy (warden.toml)

The warden.toml file configures the Warden static-analysis framework. Combined with definitions in .warden/skills/, this provides automated diff-security reviews during pull requests, scanning for vulnerabilities before code reaches the main branch.

Testing and Evaluation Framework

The evals/ directory contains the end-to-end validation suite that generates fraimz proof artifacts—canonical verification files that demonstrate UI behavior.

To execute the evaluation suite:

# Run the demo-flow fraimz test

pnpm run eval:demo-flow

This script, located in evals/demo-flow/, launches the Electron application, drives interactions via the Chrome DevTools Protocol (CDP), and produces evals/results/<run-id>/fraimz.html as definitive proof of functionality.

Security and Skill Integration

Two specialized directories integrate OpenWork with external frameworks:

OpenCode Configuration (.opencode/)

The .opencode/ directory holds skill registries and Model-Container-Protocol (MCP) definitions consumed by the desktop client at runtime. Skills are defined as JSON descriptors:

{
  "name": "my-skill",
  "description": "Performs a custom transformation on text.",
  "inputSchema": { "type": "object", "properties": { "text": { "type": "string" } } },
  "outputSchema": { "type": "object", "properties": { "result": { "type": "string" } } }
}

These definitions are referenced in AGENTS.md, which documents built-in agents and MCP endpoints.

Product Requirements (prds/)

The prds/ directory contains "product requirement documents" that serve as demo-first specifications for new features, bridging the gap between planning and implementation.

Key Files in the Root Directory

File	Role
package.json	Root-level scripts, workspace metadata, and top-level dependencies
pnpm-workspace.yaml	Workspace package locations for pnpm
turbo.json	TurboRepo pipeline configuration (build, lint, test)
warden.toml	Security-policy configuration for Warden static analysis
skills-lock.json	Lock file for skill versioning and integrity
AGENTS.md	Documentation of built-in OpenWork agents and MCP endpoints
README.md	High-level project overview and installation quick-start
changelog/	Structured changelog entries feeding auto-generated release notes

Summary

• OpenWork uses a pnpm workspace monorepo structure with clear separation between apps/ (runnable targets) and packages/ (shared libraries).
• TurboRepo orchestrates builds via turbo.json, while Warden enforces security through warden.toml and .warden/skills/.
• The evals/ directory contains fraimz-based end-to-end tests that generate proof artifacts via CDP automation.
• .opencode/ stores skill registries and MCP definitions that the desktop client consumes at runtime.
• Root configuration files (pnpm-workspace.yaml, package.json) enable cross-repository commands like pnpm dev and pnpm run eval:demo-flow.

Frequently Asked Questions

What build system does OpenWork use?

OpenWork uses pnpm for package management and TurboRepo for build orchestration. The turbo.json file defines pipelines that cache and parallelize tasks across the monorepo, ensuring only changed packages are rebuilt during development and CI.

How are new skills added to the OpenWork ecosystem?

Skills are added by creating JSON descriptors in .opencode/skills/ and referencing them in AGENTS.md. The CI pipeline automatically validates these definitions against the MCP schema, making them available to the desktop client runtime without requiring application rebuilds.

What is the purpose of the evals/ directory?

The evals/ directory contains end-to-end test suites that use the Chrome DevTools Protocol (CDP) to drive the Electron application programmatically. These tests generate fraimz HTML files—proof artifacts that serve as canonical verification that the UI behaves as expected across changes.

Where is the desktop application source code located?

The Electron-based desktop client resides in apps/desktop/, which contains the main process entry point, preload scripts, and renderer code. This application imports shared UI components from packages/ui/ and state management from packages/store/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}