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

OpenWork enforces strict TypeScript typing, pnpm-only package management, shadcn/ui-based components, and a concise-first philosophy as documented in AGENTS.md.

The 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 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 file explicitly bans three anti-patterns:

• any types
• Type casts using as
• Unnecessary fallback expressions

These restrictions are enforced through tsconfig.json, which enables strict mode settings that catch implicit any types and unsafe assignments.

Correct TypeScript Patterns

Preferred approach with explicit interfaces:

// ✅ 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:

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

The 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 is configured specifically for pnpm workspaces and features.

Correct pnpm Commands

# 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 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:

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.

Tech Stack Preferences: Default Tool Selection

When multiple libraries could solve a problem, 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:

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 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 knows `user` exists here
return user.name; // no fallback needed

Unnecessarily defensive:

// 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 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	Central document for all coding guidelines and tech stack preferences
package.json	Defines pnpm scripts and workspace configuration
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 strict settings will flag any types as compilation errors. The 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 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.

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