# Code Style Guidelines for different-ai/openwork: A Complete Developer Reference

> Explore the OpenWork code style guidelines for developers. Discover strict TypeScript typing, pnpm package management, shadcn/ui components, and concise-first principles.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: best-practices
- Published: 2026-08-05

---

**OpenWork enforces strict TypeScript typing, pnpm-only package management, shadcn/ui-based components, and a concise-first philosophy as documented in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md).**

The [different-ai/openwork](https://github.com/different-ai/openwork) repository maintains rigorous code style guidelines to ensure type safety, visual consistency, and maintainable architecture. These rules are codified in the [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) file and applied consistently across the codebase. This guide breaks down every guideline with concrete examples from the source code.

## TypeScript Guidelines: Strict Typing Without Exceptions

OpenWork mandates **explicit types everywhere** and prohibits escape hatches that undermine type safety.

### Prohibited Patterns

The [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) file explicitly bans three anti-patterns:

- `any` types
- Type casts using `as`
- Unnecessary fallback expressions

These restrictions are enforced through [`tsconfig.json`](https://github.com/different-ai/openwork/blob/main/tsconfig.json), which enables strict mode settings that catch implicit any types and unsafe assignments.

### Correct TypeScript Patterns

Preferred approach with explicit interfaces:

```typescript
// ✅ Preferred: explicit types, no `any`
interface User {
  id: string;
  email: string;
  isAdmin: boolean;
}

function isAdmin(user: User): boolean {
  return user.isAdmin;
}

```

Disallowed patterns that violate the guidelines:

```typescript
// ❌ Disallowed: usage of `any` and type assertions
function getValue(obj: any): string {
  return (obj as { value: string }).value; // ❌ avoid
}

```

The [`tsconfig.json`](https://github.com/different-ai/openwork/blob/main/tsconfig.json) configuration enforces these rules at compile time, making violations impossible to commit without explicit overrides.

## Package Management: pnpm Exclusively

OpenWork requires **pnpm as the sole package manager**. The [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) is configured specifically for pnpm workspaces and features.

### Correct pnpm Commands

```bash

# Install dependencies (pnpm only)

pnpm install

# Add a new dependency

pnpm add @tanstack/react-query

# Run scripts

pnpm dev

```

Running `npm install` or `yarn` violates the [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) guidelines and may produce incompatible lockfiles. The repository uses pnpm-specific features that other package managers cannot replicate correctly.

## UI/UX Standards: shadcn/ui and Component Reuse

All interface work follows a strict hierarchy: reuse existing components first, build new ones with shadcn/ui second.

### Component Reuse Pattern

New features should import from the centralized component library:

```tsx
import { Button } from '@/components/ui/button';

export function ConfirmButton({ onConfirm }: { onConfirm: () => void }) {
  return (
    <Button variant="primary" onClick={onConfirm}>
      Confirm
    </Button>
  );
}

```

The `src/components/ui/` directory contains the shadcn/ui-based component library. These components use **Tailwind CSS** for styling and follow consistent prop interfaces. Building custom components outside this system requires justification per [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md).

## Tech Stack Preferences: Default Tool Selection

When multiple libraries could solve a problem, [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) prescribes specific defaults to eliminate decision fatigue:

| Domain | Preferred Tool |
|--------|--------------|
| Styling | Tailwind CSS |
| Language | TypeScript |
| Framework | React |
| Components | shadcn/ui (Base UI) |
| Server State | TanStack Query |
| Client State | Zustand |
| Validation | Zod |
| ORM | Drizzle |
| Authentication | Better-Auth |

These preferences apply "when in doubt"—existing patterns in the codebase take precedence, but new work should align with this stack.

### State Management with Zustand

The `src/store/` directory demonstrates the preferred pattern:

```typescript
import { create } from 'zustand';

type CounterState = {
  count: number;
  increment: () => void;
};

export const useCounterStore = create<CounterState>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}));

```

Zustand stores should remain minimal and typed explicitly. Complex state logic is broken into smaller, composable stores rather than monolithic structures.

## General Code Style: Concise-First Philosophy

The [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) file emphasizes **simplicity over cleverness**:

- Prefer the simplest implementation that satisfies requirements
- Keep diffs minimal—avoid reformatting unrelated code
- Skip fallback expressions when TypeScript guarantees existence

### Good vs. Poor Simplicity

Acceptable:

```typescript
// TypeScript knows `user` exists here
return user.name; // no fallback needed

```

Unnecessarily defensive:

```typescript
// Redundant—TypeScript already narrowed this
return user?.name ?? 'Unknown';

```

## Workflow Guidelines: Incremental Development

Contributors must break large tasks into small, testable steps. The [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) workflow section explicitly instructs: stop if a request requires too much work at once. This prevents oversized pull requests and maintains code review quality.

## Key Files for Style Reference

| File | Purpose |
|------|---------|
| [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) | Central document for all coding guidelines and tech stack preferences |
| [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) | Defines pnpm scripts and workspace configuration |
| [`tsconfig.json`](https://github.com/different-ai/openwork/blob/main/tsconfig.json) | Enforces strict TypeScript compilation settings |
| `src/components/ui/` | shadcn/ui component library for consistent UI |
| `src/store/` | Zustand store implementations as reference patterns |

## Summary

- **TypeScript**: Explicit types only—`any`, `as`, and unnecessary fallbacks are banned
- **Package management**: pnpm exclusively; npm and yarn are prohibited
- **UI development**: Reuse `src/components/ui/` or build with shadcn/ui
- **Tech stack**: Default to Tailwind, TypeScript, React, TanStack Query, Zustand, Zod, Drizzle, and Better-Auth
- **Code philosophy**: Simplest correct solution, minimal diffs, strict typing
- **Workflow**: Small, incremental steps with testable outcomes

## Frequently Asked Questions

### What happens if I use `any` in OpenWork?

The [`tsconfig.json`](https://github.com/different-ai/openwork/blob/main/tsconfig.json) strict settings will flag `any` types as compilation errors. The [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) guidelines treat this as a blocking issue—code using `any` or `as` assertions will not pass review unless absolutely unavoidable with documented justification.

### Why does OpenWork require pnpm instead of npm or yarn?

pnpm provides deterministic installs, disk-efficient node_modules, and workspace features that the OpenWork repository relies upon. The [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) and lockfile format assume pnpm-specific behavior; other package managers produce incompatible or incorrect installations.

### How do I add a new UI component to OpenWork?

First check `src/components/ui/` for an existing component that meets your needs. If building new, use shadcn/ui's Base UI primitives and follow the Tailwind styling patterns established in nearby files. All components must include explicit TypeScript interfaces for their props.

### Where are state management examples in the OpenWork codebase?

The `src/store/` directory contains Zustand store implementations demonstrating the preferred pattern for global state. These files serve as reference implementations for type-safe, minimal state management following the repository's concise-first philosophy.