# What Is the Common Workspace in Freebuff? Purpose, Architecture, and Code Examples

> Discover the common workspace in Freebuff, its purpose, architecture, and how it centralizes shared types, schemas, and utilities across the monorepo for consistency and efficiency. Explore code examples.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: deep-dive
- Published: 2026-09-01

---

**The `common` workspace in the CodebuffAI/freebuff repository is the centralized foundation for shared types, schemas, utilities, and tools that power the CLI, SDK, agents, and runtime packages, eliminating duplication and enforcing consistency across the monorepo.**

The Freebuff project is organized as a monorepo where the `common` workspace serves as the single source of truth for reusable code. Located at the repository root, this workspace houses the type definitions, validation logic, and platform abstractions required by multiple sub-projects to maintain functional parity and type safety.

## Core Purpose of the Common Workspace

According to the repository map documented in [`AGENTS.md`](https://github.com/CodebuffAI/freebuff/blob/main/AGENTS.md), the `common/` directory contains **"shared types, tools, schemas, and utilities"** consumed by other top-level packages such as `cli/`, `sdk/`, and `agents/`. Its primary function is to decouple generic infrastructure from domain-specific logic, allowing specialized packages to import canonical definitions rather than reimplementing them.

### Centralized Type Definitions

The workspace exports canonical interfaces that prevent type drift between packages. For instance, the `Skill` type defined in [`common/src/util/skills.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/skills.ts) provides the authoritative structure for agent capabilities. When the CLI, SDK, and agent runtime all import `Skill` from this single file, they guarantee compatible data shapes across process boundaries.

### Reusable Schema Validation

Validation logic is consolidated in [`common/src/util/zod-schema.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/zod-schema.ts), which exports helpers like `createZodSchema`. By centralizing Zod builders here, the codebase ensures that runtime validation rules remain identical whether executing in a server-side SDK method or a local CLI command.

### Cross-Cutting Utilities

Generic infrastructure—such as XML parsing in [`common/src/util/xml-parser.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/xml-parser.ts) and user-interaction bridges in [`common/src/util/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/ask-user-bridge.ts)—resides in `common/` to abstract platform specifics. This allows both interactive CLI tools and headless agents to share identical I/O patterns without duplicating implementation details.

## Key Files and Their Roles

- **[`common/src/util/skills.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/skills.ts)** – Defines the `Skill` interface and runtime helpers that describe invocable agent capabilities.
- **[`common/src/util/zod-schema.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/zod-schema.ts)** – Houses `createZodSchema` and other Zod-based utilities for consistent data validation.
- **[`common/src/util/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/ask-user-bridge.ts)** – Implements the `askUser` bridge for prompting users, usable across CLI and agent contexts.
- **[`common/src/util/xml-parser.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/xml-parser.ts)** – Provides shared XML parsing utilities for data ingestion tasks.

## Practical Implementation Examples

### Importing Shared Types

Agents and CLI commands reference the same `Skill` definition to ensure interoperability:

```typescript
// agents/thinker/thinker.ts
import type { Skill } from "common/src/util/skills";

function executeSkill(skill: Skill) {
  // Implementation uses the canonical Skill structure
  console.log(`Executing skill: ${skill.name}`);
}

```

### Validating Data with Shared Schemas

The SDK leverages centralized Zod helpers to maintain consistent validation:

```typescript
// sdk/src/models/user.ts
import { createZodSchema } from "common/src/util/zod-schema";
import { z } from "zod";

export const UserSchema = createZodSchema({
  id: z.string(),
  email: z.string().email(),
});

```

### Reusing User-Interaction Logic

CLI initialization scripts and agents share the same prompting mechanism:

```typescript
// cli/commands/init.ts
import { askUser } from "common/src/util/ask-user-bridge";

async function configureProject() {
  const projectName = await askUser("Project name?");
  return projectName;
}

```

## Benefits for Monorepo Architecture

- **Consistency** – Types like `Skill` and validation schemas in [`common/src/util/zod-schema.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/zod-schema.ts) are defined once and imported everywhere, preventing interface mismatches.
- **Maintainability** – Updates to a utility in [`common/src/util/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/ask-user-bridge.ts) propagate automatically to every consumer, reducing regression risk.
- **Clear Boundaries** – Domain packages focus on business logic while delegating generic concerns (parsing, validation, I/O) to `common/`.

## Summary

- The `common` workspace is the foundational shared library in the CodebuffAI/freebuff monorepo, explicitly mapped in [`AGENTS.md`](https://github.com/CodebuffAI/freebuff/blob/main/AGENTS.md).
- It exports critical code from [`common/src/util/skills.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/skills.ts), [`common/src/util/zod-schema.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/zod-schema.ts), and [`common/src/util/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/ask-user-bridge.ts) for use across CLI, SDK, and agent packages.
- Centralizing utilities eliminates code duplication and ensures that type definitions remain synchronized across the entire codebase.
- Files like [`common/src/util/xml-parser.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/xml-parser.ts) demonstrate how platform-agnostic logic is abstracted for reuse.

## Frequently Asked Questions

### What types of code belong in the common workspace?

Code that is imported by two or more distinct packages belongs in the common workspace. This includes type definitions such as `Skill` in [`common/src/util/skills.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/skills.ts), validation helpers in [`common/src/util/zod-schema.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/zod-schema.ts), and platform abstractions like the `askUser` bridge in [`common/src/util/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/ask-user-bridge.ts). Package-specific business logic should remain in its respective `cli/`, `sdk/`, or `agents/` directory.

### How do other packages import from the common workspace?

Other packages import directly from the `common/src/` tree using relative or configured path aliases. For example, `import { Skill } from "common/src/util/skills"` allows both the CLI and agent runtime to share identical type definitions without maintaining separate copies or publishing distinct npm packages.

### Is the common workspace published as a standalone package?

Based on the repository structure described in [`AGENTS.md`](https://github.com/CodebuffAI/freebuff/blob/main/AGENTS.md), the common workspace operates as an internal shared module within the monorepo rather than an independently versioned package. This design ensures tight coupling with the current codebase state and simplifies refactoring across package boundaries.

### How does the common workspace improve developer experience?

By centralizing utilities like `createZodSchema` from [`common/src/util/zod-schema.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/zod-schema.ts) and the `askUser` bridge from [`common/src/util/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/util/ask-user-bridge.ts), developers rely on battle-tested, consistent implementations across CLI tools, SDK methods, and agent runtimes without rewriting validation or I/O logic for each package.