How to Contribute to different-ai/openwork: A Complete Developer Guide

To contribute to different-ai/openwork, fork the repository, install dependencies with pnpm install, run pnpm dev:worktree for isolated development, make changes in the appropriate package layer, and open a pull request after running pnpm test:e2e.

The different-ai/openwork repository is a comprehensive monorepo powering a desktop AI-workflow client, a cloud-hosted "Den" control plane, and a modular ecosystem of reusable skills and plugins. This guide walks you through every layer of the codebase and provides exact commands and file paths to start contributing confidently.

---

Understanding the OpenWork Monorepo Architecture

OpenWork uses pnpm workspaces orchestrated by TurboRepo to manage dozens of interdependent packages. Knowing which layer handles what saves hours of exploration.

Workspace and Build System

The root configuration defines how code moves from source to production:

• pnpm-workspace.yaml – Declares all packages in the monorepo
• turbo.json – Configures parallel task pipelines (build, test, lint)

# See all workspace packages

cat pnpm-workspace.yaml

Core Desktop Application (@openwork/app)

The Electron-based UI splits cleanly between front-end and native glue:

Directory	Purpose
packages/app/src/react-app	React components, routing, and state management
packages/app/src/electron	Electron main process and native integrations

OpenWork Den (Cloud Control Plane)

Enterprise-tier services live under packages/ee/:

• packages/ee/den-api – API server for authentication and model provisioning
• packages/ee/den-web – Web-based management interface
• packages/ee/den-db – Prisma schema and database migrations

Skills and Plugins (OpenCode Integration)

Reusable AI capabilities ship as OpenCode skills in .opencode/skills/. Each skill folder contains a SKILL.md that auto-registers with the runtime. Example: .opencode/skills/build-a-witness creates deterministic test witnesses for validation.

Development and Testing Infrastructure

Tool	Location	Purpose
scripts/dev-local.mjs	scripts/	Boots Den and desktop app simultaneously
scripts/release/prepare.mjs	scripts/release/	Automates version bumps and changelogs
evals/runner/run.mjs	evals/	End-to-end test orchestration
Package test/ folders	Per-package	Unit tests using framework of choice

---

Step-by-Step Contribution Workflow

1. Fork and Clone the Repository

git clone https://github.com/<your-username>/openwork.git
cd openwork

2. Install Dependencies

OpenWork requires pnpm (not npm or yarn). The lockfile ensures reproducible installs:

pnpm install

3. Start the Local Development Environment

Two modes support different workflows:

pnpm dev – Single checkout, standard development pnpm dev:worktree – Isolated profile for parallel instances (recommended for active contributors)

# Recommended: isolated worktree with unique profile

pnpm dev:worktree

# Output: [openwork] dev profile=worktree-123 cdp=http://127.0.0.1:9223

Environment variables for API keys and service endpoints are documented in the README's Local development section.

4. Make Targeted Changes

Contribution Type	Target Directory
UI components or React logic	packages/app/src/react-app/...
Electron native features	packages/app/src/electron/...
Den API endpoints	packages/ee/den-api/...
New OpenCode skill	.opencode/skills/your-skill-name/ (include SKILL.md)

5. Run Appropriate Tests

Unit tests for specific package:

pnpm --filter @openwork/app test

# Replace @openwork/app with @openwork-ee/den-api, etc.

Full end-to-end suite (mandatory before PR):

pnpm test:e2e

# Launches Den, Electron, and executes all @openwork/testkit specifications

6. Commit and Open Pull Request

Follow the automatic PR template: describe changes, attach screenshots for UI modifications, and reference related issues. The CI pipeline validates lint, type-checking, and tests on every push.

---

Practical Code Examples for Contributors

Example 1: Creating a New OpenCode Skill

Skills auto-load when placed in .opencode/skills/ with a SKILL.md:

mkdir -p .opencode/skills/hello-world

cat > .opencode/skills/hello-world/SKILL.md <<'EOF'

# Hello World Skill

## Description

Returns a greeting from the OpenWork runtime.

## Implementation

```ts
export async function run(context) {
  return "👋 Hello from OpenWork!"
}

EOF

Restart the dev server to register the new skill.

### Example 2: Publishing Package Updates

Maintainers use version-bump scripts with automatic changelog generation:

```bash

# Bump @openwork/app from 0.1.2 → 0.1.3

pnpm bump:patch

# Available: bump:patch, bump:minor, bump:major

---

Essential Files Every Contributor Should Know

File	Purpose	Direct Link
README.md	Installation, dev commands, environment setup	README.md
package.json	Workspace scripts and pnpm metadata	package.json
pnpm-workspace.yaml	Monorepo package registry	pnpm-workspace.yaml
turbo.json	TurboRepo pipeline configuration	turbo.json
AGENTS.md	Agent model and interaction patterns	AGENTS.md
TRANSLATIONS.md	Localization guidelines	TRANSLATIONS.md
CODE_OF_CONDUCT.md	Community standards	CODE_OF_CONDUCT.md

---

Advanced Development Patterns

Running Multiple Dev Instances Simultaneously

The pnpm dev:worktree command generates isolated profiles with unique Chrome DevTools Protocol ports. This prevents state collision when testing multi-user scenarios or comparing feature branches side-by-side.

Local Stack Orchestration

scripts/dev-local.mjs coordinates the Den control plane and desktop application in one terminal:

node scripts/dev-local.mjs

# Equivalent to manually starting den-api, den-web, and @openwork/app

---

Summary

• Fork, clone, and install with pnpm install to begin contributing to different-ai/openwork
• Use pnpm dev:worktree for isolated development environments that support parallel instances
• Target the correct layer: React UI in packages/app/src/react-app/, API changes in packages/ee/den-api/, skills in .opencode/skills/
• Always run pnpm test:e2e before submitting pull requests to validate end-to-end behavior
• Reference AGENTS.md and TRANSLATIONS.md for specialized contribution types

---

Frequently Asked Questions

What package manager does openwork require?

pnpm is mandatory. The pnpm-workspace.yaml and pnpm-lock.yaml files define the monorepo structure. Using npm or yarn will produce inconsistent dependency trees and fail CI validation.

How do I test changes to an OpenCode skill?

Create your skill in .opencode/skills/your-name/ with a SKILL.md file, restart the dev server with pnpm dev:worktree, and invoke the skill through the OpenWork desktop app. The runtime auto-discovers any valid skill directory.

What should I do before opening a pull request?

Run the full validation suite: pnpm test:e2e executes end-to-end tests across the Den, Electron, and skill systems. Additionally, ensure your branch passes pnpm lint and pnpm type-check—these run automatically in CI but catching errors locally speeds review.

How does the Den control plane differ from the desktop app?

The Den (packages/ee/den-*) is a cloud-hosted service stack handling authentication, organization management, and model provisioning. The desktop app (packages/app) is a local Electron client that optionally connects to a Den instance. Contributing to Den requires database migrations in packages/ee/den-db/, while desktop work focuses on React and Electron code.

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