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

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, 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 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, 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 and user-interaction bridges in 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 – Defines the Skill interface and runtime helpers that describe invocable agent capabilities.
• common/src/util/zod-schema.ts – Houses createZodSchema and other Zod-based utilities for consistent data validation.
• 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 – 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:

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

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

// 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 are defined once and imported everywhere, preventing interface mismatches.
• Maintainability – Updates to a utility in 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.
• It exports critical code from common/src/util/skills.ts, common/src/util/zod-schema.ts, and 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 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, validation helpers in common/src/util/zod-schema.ts, and platform abstractions like the askUser bridge in 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, 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 and the askUser bridge from 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.

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