Creating Domains

Domains are knowledge overlays that enhance agents with industry-specific vocabulary, metrics, frameworks, and reasoning patterns. They do not replace agent definitions — they extend them.

When you activate a domain (e.g., --domain saas), the runtime merges domain-specific enhancements into each agent before the session starts. The Catalyst still thinks like the Catalyst, but now it also knows about ARR, churn rate, and CAC payback periods.

A complete domain.yaml:

schema: aos/domain/v1                   # Required. Schema identifier.
id: saas                                # Unique domain ID.
name: SaaS Business Context             # Display name.
description: >                          # What this domain adds.
  Domain pack for B2B and B2C SaaS
  businesses. Injects SaaS-specific
  lexicon, metrics, and agent overlays
  for subscription-based software.
version: 1.0.0

lexicon:                                # Industry vocabulary.
  metrics:
    - "ARR — Annual Recurring Revenue"
    - "MRR — Monthly Recurring Revenue"
    - "NRR — Net Revenue Retention"
    - "CAC — Customer Acquisition Cost"
    - "LTV — Lifetime Value"
    - "churn_rate — % customers or revenue lost per period"
  frameworks:
    - "PLG — Product-Led Growth"
    - "sales_led — Enterprise sales motion"
    - "land_and_expand — Start narrow, expand over time"
  stages:
    - "pre_seed — Pre-PMF, team and hypothesis"
    - "seed — Early traction, proving PMF"
    - "series_a — Scaling GTM, $1M-$10M ARR"
    - "growth — Scaling revenue efficiently"
    - "scale — Optimizing unit economics at scale"

overlays:                               # Per-agent enhancements.
  catalyst:
    thinking_patterns:
      - "Quantify impact on ARR or MRR for every opportunity"
      - "Challenge any initiative where CAC payback > 18 months"
    heuristics:
      - name: SaaS Revenue Test
        rule: "Quantify direct impact on ARR or MRR expansion."
      - name: Payback Obsession
        rule: "Challenge any initiative where CAC payback > 18 months."
    evidence_standard:
      convinced_by:
        - "Revenue claims with conversion rate, ACV, and time-to-close"
      not_convinced_by:
        - "Revenue claims without conversion rate assumptions"

  sentinel:
    thinking_patterns:
      - "Treat NRR below 100% as existential"
      - "Assess whether decisions increase or decrease switching costs"
    heuristics:
      - name: NRR Focus
        rule: "Treat NRR below 100% as existential. Flag churn-accelerating decisions."
      - name: Switching Costs
        rule: "Assess impact on customer switching costs."

  architect:
    thinking_patterns:
      - "Evaluate against 10x customer base with same team"
      - "Track ops cost per customer — must decline at scale"
    heuristics:
      - name: Multi-Tenant Scale
        rule: "Evaluate against 10x customers with the same team."

  provocateur:
    thinking_patterns:
      - "Challenge growth projections against SaaS benchmarks"
      - "Model competitor counterfactual for every strategic move"
    heuristics:
      - name: SaaS Base Rate Check
        rule: "Require published benchmark comparison for growth projections."

additional_input_sections:
  - heading: "## Metrics"
    guidance: >
      Current ARR, MRR, NRR, churn rate,
      CAC, LTV, payback period.

additional_output_sections:
  - section: financial_impact
    description: >
      Projected impact on ARR, churn,
      and unit economics for each path.

guardrails:
  - "Revenue projections must state conversion rate, ACV, volume, and time horizon"
  - "Recommendations with churn risk must include churn impact assessment"
  - "Initiatives with CAC payback > 24 months require CFO-level justification"

The lexicon block defines the shared vocabulary that all agents in the session will understand. It has three sub-sections.

metrics — Standard measurements and their definitions. Agents reference these consistently when discussing quantitative data.

frameworks — Industry models and strategies. Agents can reference these by name (e.g., "this is a PLG motion") and all participants share the same definition.

stages — Business lifecycle stages. Agents calibrate their advice based on the company's current stage.

aos run strategic-council --brief brief.md --domain saas

aos run strategic-council --brief brief.md --domain saas --domain fintech

The overlays block defines per-agent enhancements. Each key is an agent ID, and the value contains the fields to merge.

Overlay-able fields (any or all can be specified per agent):

• thinking_patterns — Additional questions the agent asks itself
• heuristics — Additional named decision rules
• evidence_standard.convinced_by — Additional evidence the agent accepts
• evidence_standard.not_convinced_by — Additional evidence the agent rejects
• red_lines — Additional hard limits

You only need to define overlays for agents that benefit from domain-specific enhancement. If an agent does not have an overlay entry, it participates unchanged.

overlays:
  catalyst:
    thinking_patterns:
      - "Quantify impact on ARR or MRR for every opportunity"
    heuristics:
      - name: SaaS Revenue Test
        rule: "Quantify direct impact on ARR or MRR expansion."
    evidence_standard:
      convinced_by:
        - "Revenue claims with conversion rate, ACV, and time-to-close"
      not_convinced_by:
        - "Revenue claims without conversion rate assumptions"

When a domain is activated, the runtime merges overlay values into agent definitions using these rules:

When multiple domains are active, overlays from all domains are appended in the order the domains are specified. If both saas and fintech domains define thinking_patterns for the Catalyst, the Catalyst gets both sets appended to its base patterns.

Walk through creating a SaaS domain pack from scratch.

Step 1 — Create the directory

mkdir -p core/domains/saas

Step 2 — Define the lexicon

Start with the metrics your agents need to speak fluently:

lexicon:
  metrics:
    - "ARR — Annual Recurring Revenue: annualized subscription contracts"
    - "MRR — Monthly Recurring Revenue: monthly subscription revenue"
    - "NRR — Net Revenue Retention: retained + expanded revenue from existing customers"
    - "CAC — Customer Acquisition Cost: fully loaded cost to acquire one customer"
    - "LTV — Lifetime Value: projected total revenue from a customer"
    - "churn_rate — % of customers or revenue lost per period"
    - "expansion_revenue — Additional revenue from upsell, cross-sell, seat growth"
    - "payback_period — Months of gross margin to recover CAC"
  frameworks:
    - "PLG — Product-Led Growth: product drives acquisition and expansion"
    - "sales_led — Enterprise sales motion drives acquisition"
    - "hybrid_motion — PLG for SMB + sales-led for enterprise"
    - "land_and_expand — Narrow beachhead, expand over time"
  stages:
    - "pre_seed — Pre-PMF; team and hypothesis"
    - "seed — Early traction; proving PMF with a cohort"
    - "series_a — Scaling GTM; $1M-$10M ARR"
    - "growth — Scaling revenue efficiently; building category"
    - "scale — Optimizing unit economics; preparing for IPO/M&A"

Step 3 — Add agent overlays

Think about what each agent needs to know about SaaS. The Catalyst needs revenue metrics. The Sentinel needs churn and retention signals. The Architect needs scalability heuristics.

overlays:
  catalyst:
    thinking_patterns:
      - "For every opportunity, quantify its direct impact on ARR or MRR expansion"
      - "Challenge any initiative where CAC payback exceeds 18 months"
    heuristics:
      - name: SaaS Revenue Test
        rule: "Quantify direct impact on ARR or MRR expansion for every opportunity."
      - name: Payback Obsession
        rule: "Challenge any initiative where CAC payback exceeds 18 months."

  sentinel:
    thinking_patterns:
      - "Treat NRR below 100% as an existential signal"
      - "Assess whether the decision increases or decreases customer switching costs"
    heuristics:
      - name: NRR Focus
        rule: "Treat NRR below 100% as existential. Flag churn-accelerating decisions."
      - name: Switching Costs
        rule: "Assess whether the decision increases or decreases switching costs."

Step 4 — Add guardrails

Guardrails are validation rules that apply to the entire session. The runtime flags outputs that violate them.

guardrails:
  - "Revenue projections must state assumptions on conversion rate, ACV, volume, and time horizon"
  - "Recommendations with material churn risk must include a churn impact assessment"
  - "Initiatives projecting CAC payback beyond 24 months require CFO-level justification"

Step 5 — Validate

aos validate domain core/domains/saas/domain.yaml

The validator checks:

• Schema version is aos/domain/v1
• All required fields present (id, name, lexicon)
• Overlay agent IDs reference agents that exist
• Overlay fields use valid merge-able field names
• Guardrails are non-empty strings

Step 6 — Use it

aos run strategic-council --brief brief.md --domain saas

Every agent in the session now has SaaS-specific vocabulary, thinking patterns, and heuristics merged into their base definitions. The Catalyst will quantify ARR impact. The Sentinel will flag NRR risks. The Provocateur will demand SaaS benchmark comparisons.