Creating Agents

Every agent is a directory containing two files:

core/agents/perspectives/
  catalyst/
    agent.yaml      # Schema, cognition, persona, tensions, capabilities
    prompt.md        # Full prompt template with {{variables}}

agent.yaml defines the agent's structured identity — how it thinks, what it values, who it clashes with, and what it can produce. The runtime reads this file to configure the agent before each session.

prompt.md is the full prompt sent to the LLM. It uses template variables (like {{brief}}, {{role_override}}, {{participants}}) that the runtime injects at execution time.

A complete agent.yaml with every field annotated:

schema: aos/agent/v1                    # Required. Schema identifier.
id: catalyst                            # Unique agent ID. Lowercase, hyphenated.
name: Catalyst                          # Display name.
role: >                                 # One-line role description.
  Acceleration and monetization
  strategist. Pushes for commercial
  velocity and shipping speed.

cognition:                              # How the agent thinks.
  objective_function: >                 #   North star optimization target.
    Maximize momentum and commercial
    velocity. Ship, sell, collect.
  time_horizon:                         # Planning horizons.
    primary: 30-90 days                 #   Main focus window.
    secondary: this quarter             #   Awareness range.
    peripheral: next quarter            #   Peripheral vision.
  core_bias: speed-and-monetization     # Named cognitive bias.
  risk_tolerance: moderate              # low | moderate | high
  default_stance: >                     # Opening position in any debate.
    I want a version customers will
    pay for in 90 days.

persona:                                # Behavioral personality.
  temperament:                          # Character traits.
    - "Impatient — treats delays as costs"
    - "Revenue-obsessed"
    - "Action-biased"
    - "Direct"
  thinking_patterns:                    # Internal monologue patterns.
    - "Who will pay for this, and how much?"
    - "What is the fastest path to revenue?"
  heuristics:                           # Named decision rules.
    - name: Ship-It Rule
      rule: >
        If a version can ship in half the time,
        default to shipping it — unless
        irreversibility risk is proven.
    - name: Payback Period
      rule: >
        Every initiative must have a payback
        period under 6 months.
  evidence_standard:                    # What convinces or fails to convince.
    convinced_by:
      - "Revenue data and conversion metrics"
      - "Concrete timelines with ship dates"
    not_convinced_by:
      - "Abstract quality arguments without revenue impact"
      - "Timelines that keep extending"
  red_lines:                            # Hard boundaries.
    - "Never accept an indefinite timeline"
    - "Never ignore unit economics"

tensions:                               # Productive conflict definitions.
  - agent: sentinel                     #   ID of the opposing agent.
    dynamic: >                          #   Description of the tension.
      Ship now vs. protect long-term.
      Catalyst pushes speed; Sentinel
      demands sustainability.

report:                                 # How the agent structures output.
  structure: >
    Lead with revenue opportunity.
    State the recommended path with a
    concrete ship date.

model:                                  # LLM configuration.
  tier: standard                        #   standard | advanced | reasoning
  thinking: "off"                       #   off | on (extended thinking)

capabilities:                           # What this agent can produce.
  can_execute_code: false
  can_produce_files: false
  can_review_artifacts: true
  available_skills: []
  output_types: [text, markdown]

tools: null                             # External tool integrations (future).
skills: []                              # Linked skill definitions.
expertise:                              # Persistent scratch pad.
  - path: expertise/catalyst-notes.md
    mode: read-write

The cognition block defines how the agent thinks — its optimization target, time horizon, biases, and risk appetite.

objective_function is the agent's north star. Every argument, recommendation, and challenge the agent makes should trace back to this function. Make it specific and measurable.

core_bias names the agent's intentional cognitive lean. This is not a flaw — it is a design choice. Agents are biased on purpose so that the council produces genuine tension. Examples: speed-and-monetization, risk-aversion, systems-thinking, user-empathy, contrarian.

risk_tolerance (low / moderate / high) controls how the agent weighs uncertain outcomes. A low agent demands proof before acting. A high agent acts on signal and adjusts.

time_horizon defines three nested windows. The primary horizon is where the agent does most of its thinking. The secondary is awareness. The peripheral is what it notices but does not prioritize.

The persona block defines who the agent is — its character, patterns of reasoning, decision rules, evidence standards, and hard limits.

temperament is a list of character traits written as short descriptions. These set the tone for how the agent communicates. Write them as "Trait — explanation" pairs.

thinking_patterns are the internal questions the agent asks itself when evaluating any input. Write them as questions the agent would ask.

heuristics are named decision rules. Each has a name (short, memorable) and a rule (one or two sentences). Good heuristics are opinionated and actionable.

evidence_standard has two lists: convinced_by (what counts as good evidence) and not_convinced_by (what the agent rejects). This controls how the agent responds to other agents' arguments.

red_lines are absolute limits. The agent will never cross these regardless of the discussion. Keep the list short (2-4 items) and specific.

Tensions define the productive conflicts between agents. They are the engine of deliberation.

tensions:
  - agent: sentinel
    dynamic: >
      Ship now vs. protect long-term. The Catalyst
      pushes for speed; the Sentinel demands
      sustainability. The tension is whether velocity
      creates value or destroys trust.
  - agent: pathfinder
    dynamic: >
      Proven revenue vs. speculative bets. The Catalyst
      wants to monetize the known; the Pathfinder wants
      to bet on the unknown.

Each tension entry names the opposing agent by ID and describes the dynamic — the specific disagreement that makes this pairing valuable.

The capabilities block declares what an agent can produce during sessions.

capabilities:
  can_execute_code: false       # Run code in a sandboxed environment
  can_produce_files: false      # Write files to the output directory
  can_review_artifacts: true    # Read and critique other agents' outputs
  available_skills: []          # Skill IDs the agent can invoke
  output_types:                 # What formats this agent produces
    - text
    - markdown

For execution profiles, agents with can_produce_files: true generate artifacts (architecture docs, task breakdowns) that become part of the execution package. Agents with can_review_artifacts: true can read and critique those artifacts in later workflow steps.

output_types declares the formats this agent can produce: text, markdown, json, yaml, mermaid, code.

The prompt.md file uses {{variable}} placeholders that the runtime injects at execution time.

• Start with identity. The first section of prompt.md should establish who the agent is, what it cares about, and why it exists.
• Use second person. Write "You are the Catalyst" not "The Catalyst is." Direct address produces stronger role adherence.
• Include example reasoning. Show the agent's internal monologue with quoted examples.
• Define engagement rules. Tell the agent how to interact with specific other agents.
• Keep red lines few and firm. 2-4 hard limits. If you list 10, the LLM treats them all as soft.
• Use {{role_override}} as an insertion point. Place it after the identity section so profile-specific instructions layer on top of the base persona.
• End with report structure. Tell the agent exactly how to format its output. Numbered steps work better than vague instructions.

Validate your agent definition against the schema:

aos validate agent core/agents/perspectives/my-agent/agent.yaml

The validator checks:

• Schema version is aos/agent/v1
• All required fields are present (id, name, role, cognition, persona)
• Tension references point to agents that exist
• Capability fields use valid values
• prompt.md exists in the same directory

To validate all agents at once:

aos validate agents