Workspace Context: Defining Your Domain

A workspace without a defined context is just a folder with files. A workspace with a defined context is a team's domain — it knows what it owns, how it speaks, and where its boundaries are.

The workspace context is a declaration file that captures this. It lives in your workspace and is used by Fabriq to scope CDR scans, guide agent behavior, and document what your team is responsible for.

Why define context

Without context:

• The agent has to guess what domain it's working in
• CDR scans have no boundary — they scan everything or nothing
• New team members rely on tribal knowledge to understand what's in scope
• Cross-team dependencies are undocumented

With context:

• The agent knows its domain language before it starts coding
• CDR scans scope to your bounded context — relevant results, less noise
• New team members read the context file and understand the landscape
• Upstream/downstream dependencies are explicit

The context file

A workspace context file defines:

domain: order-fulfillment
team: platform-fulfillment-team

# What this workspace owns
bounded-context: |
  This workspace covers the order fulfillment domain — from 
  order placement through shipment. It owns order lifecycle 
  management, inventory reservation, shipment scheduling, 
  and returns processing.

# The language this domain speaks
ubiquitous-language:
  Order: A customer's request to purchase items. Contains OrderLines.
  OrderLine: An individual item within an order (product + quantity + price).
  Shipment: A physical package sent to the customer. May contain items from multiple Orders.
  FulfillmentCenter: A warehouse or distribution center that processes shipments.
  Return: A customer's request to send back purchased items.

# Where this team's code lives
repos:
  - order-service          # Order lifecycle management
  - fulfillment-api        # Fulfillment and shipment processing
  - return-flow            # Returns processing

# Dependencies — who this context talks to
contracts:
  upstream:                # These send events/data INTO this context
    - payment-context      # Payment confirmation triggers fulfillment
    - inventory-context    # Inventory availability affects fulfillment
    
  downstream:              # This context sends events/data TO these
    - shipping-context     # Shipment requests go to logistics providers
    - notification-context # Customer notifications

# What's explicitly out of scope
out-of-scope:
  - Payment processing (owned by payment-context)
  - User authentication (owned by identity-context)
  - Product catalog management (owned by catalog-context)

Fields explained

Field	What it defines	Why it matters
domain	The name of your bounded context	Everything in this workspace should relate to this domain
team	Who owns this context	Ownership clarity — used for routing and notification
bounded-context	Prose description of scope	Quick orientation for new members and AI agents
ubiquitous-language	Key terms and their definitions	Shared vocabulary — the single most important artifact for communication between humans and agents
repos	Code repositories within this context	Scopes CDR analysis, determines context boundaries
contracts.upstream	Contexts feeding data into yours	Identifies dependencies — when upstream changes, your domain may need to react
contracts.downstream	Contexts consuming your data	Knows who depends on you — helps assess change impact
out-of-scope	Explicitly excluded responsibilities	Prevents scope creep, clarifies boundaries

How context is used

By Fabriq's engine

• CDR scope: When scanning, the engine focuses on repos within this context. Results from out-of-scope repos are still available but tagged as "external."
• Agent context injection: The context file is automatically included in the agent's runtime-context. The agent knows your domain language and boundaries without being told.
• Feature creation: When you name a feature, the engine can validate that it stays within context scope.

By the CDR pipeline

• Domain analysis uses the context boundary to group entities into domains
• Business rules are tagged with their workspace context
• Cross-context behaviors are identified (e.g., "this behavior calls an endpoint in the payment-context")

By your team

• Onboarding: new members read the context file, not scattered docs
• Design: feature descriptions can reference context terms with shared meaning
• Review: everyone agrees on what "Order" means

Getting started with context

Step 1: Define your domain

Start with the most basic declaration:

domain: order-fulfillment
team: platform-fulfillment-team
bounded-context: "Order fulfillment — from placement to shipment"

Step 2: Add your repos

Register the repos your team owns:

repos:
  - order-service
  - fulfillment-api

Step 3: Document your language

This is the highest-leverage step. List your core entities and define them in one sentence each:

ubiquitous-language:
  Order: A customer's purchase request.
  Shipment: A physical package of items.

Start small (3-5 terms) and grow as you discover new concepts.

Step 4: Identify dependencies

List upstream and downstream contexts at the right granularity — context names, not service names:

contracts:
  upstream:
    - payment-context
  downstream:
    - shipping-context

Step 5: Update as you learn

Workspace context is a living document. Update it when:

• A new entity enters your domain language
• A new dependency emerges
• Your team's scope changes
• CDR discovers something that challenges your boundaries

Context vs runtime-context.md

	Workspace Context	runtime-context.md
Purpose	Domain boundary declaration	Technical project details for agent
Audience	Team + Agents	Agents (primarily)
Persistence	Permanent, changes slowly	Changes per feature
Content	Domain, language, contracts, scope	Architecture, conventions, file paths
Who maintains	Tech lead / team	Individual engineers

Both are injected to the agent. The workspace context provides domain-level orientation; runtime-context.md provides technical specifics.

Example: A complete workspace context

domain: order-fulfillment
team: platform-fulfillment-team

bounded-context: |
  Order fulfillment covers everything from the moment a customer 
  places an order to the moment items arrive at their door. This 
  includes order lifecycle management, inventory reservation, 
  shipment processing, and returns handling.

ubiquitous-language:
  Order: A customer request to purchase one or more items.
  OrderLine: A product + quantity entry within an Order.
  Shipment: A physical package sent to the customer.
  FulfillmentCenter: A warehouse that processes shipments.
  Carrier: The logistics company delivering the package (e.g., UPS, FedEx).
  Return: A customer sending items back.
  RMA: Return Merchandise Authorization — a return tracking number.

contracts:
  upstream:
    - payment-context
    - inventory-context
  downstream:
    - shipping-context
    - notification-context

out-of-scope:
  - Payment processing
  - User identity and authentication
  - Product catalog and pricing
  - Customer support ticketing

Next steps

• Workspaces: Your Team's Domain — the concept of workspace as bounded context
• Adding Repositories — register code within your context
• CDR Overview — scan your context for domain knowledge
• Injecting Context — how workspace context reaches the agent
• Concepts: Two Surfaces — workspace vs feature dimensions