Creating Profiles

AOS supports two profile patterns. Choose based on whether you need a decision or a deliverable.

A complete profile.yaml with all fields:

schema: aos/profile/v1                  # Required. Schema identifier.
id: strategic-council                   # Unique profile ID.
name: Strategic Council                 # Display name.
description: >                          # What this profile does.
  Multi-perspective strategic
  deliberation. Agents debate and
  the Arbiter synthesizes a memo.
version: 1.0.0

assembly:                               # Who participates.
  orchestrator: arbiter                 # Agent ID of the orchestrator.
  perspectives:                         # List of participating agents.
    - agent: catalyst
      required: true
    - agent: sentinel
      required: true
    - agent: architect
      required: true
    - agent: provocateur
      required: true
      structural_advantage: speaks-last
    - agent: navigator
      required: false
    - agent: operator
      required: false

delegation:                             # How work is distributed.
  default: broadcast                    # broadcast | targeted
  opening_rounds: 1                     # Broadcast rounds before targeting.
  tension_pairs:                        # Paired for productive conflict.
    - [catalyst, sentinel]
    - [architect, pathfinder]
    - [advocate, navigator]
  bias_limit: 5                         # Max consecutive turns by one agent.

constraints:                            # Session boundaries.
  time:
    min_minutes: 2
    max_minutes: 10
  budget:
    min: 1.00
    max: 10.00
    currency: USD
  rounds:
    min: 2
    max: 8

error_handling:                         # Failure modes.
  agent_timeout_seconds: 120
  retry_policy:
    max_retries: 2
    backoff: exponential
  on_agent_failure: skip
  on_orchestrator_failure: save_transcript_and_exit
  partial_results: include_with_status_flag

budget_estimation:                      # Token budget management.
  strategy: rolling_average
  fixed_estimate_tokens: 2000
  safety_margin: 0.15
  on_estimate_exceeded: drop_optional

input:                                  # Brief format requirements.
  format: brief
  required_sections:
    - heading: "## Situation"
      guidance: "What is happening right now?"
    - heading: "## Stakes"
      guidance: "What's at risk?"
    - heading: "## Constraints"
      guidance: "Boundaries and limits."
    - heading: "## Key Question"
      guidance: "The single question to answer."
  context_files: true

output:                                 # What the profile produces.
  format: memo
  path_template: "output/memos/{{date}}-{{brief_slug}}-{{session_id}}/memo.md"
  sections:
    - ranked_recommendations
    - agent_stances
    - dissent_and_tensions
    - tradeoffs_and_risks
    - next_actions
    - deliberation_summary
  artifacts:
    - type: diagram
  frontmatter:
    - date
    - duration
    - budget_used
    - participants

expertise:                              # Persistent agent memory.
  enabled: true
  path_template: "expertise/{{agent_id}}-notes.md"
  mode: per-agent

controls:                               # Runtime controls.
  halt: true
  wrap: true
  interject: false

The assembly block defines who participates in the session.

orchestrator is the agent ID of the session leader. For deliberation, use arbiter (neutral facilitator). For execution, use a domain-specific orchestrator like cto-orchestrator.

perspectives lists participating agents. Each entry has:

• agent — Agent ID (must exist in core/agents/)
• required — If true, always included. If false, can be deactivated or dropped by budget estimation.
• structural_advantage — Optional. Currently supports speaks-last, guaranteeing the agent gives its position after hearing all others.
• role_override — Optional. Injected into the agent's {{role_override}} template variable to specialize it for this profile.

perspectives:
  - agent: architect
    required: true
    role_override: "Produce architecture decision records and system design docs"
  - agent: provocateur
    required: false
    structural_advantage: speaks-last
    role_override: "Stress-test the plan. Find the gaps."

The delegation block controls how the orchestrator distributes work.

default sets the mode:

• broadcast — Every agent sees every message. Used in deliberation.
• targeted — The orchestrator sends specific tasks to specific agents. Used in execution.

opening_rounds sets how many broadcast rounds happen before the orchestrator can begin targeting. Set to 1 for deliberation and 0 for execution.

tension_pairs lists pairs of agents brought into direct dialogue for productive conflict:

tension_pairs:
  - [catalyst, sentinel]       # Speed vs. sustainability
  - [architect, pathfinder]    # Proven patterns vs. novel approaches
  - [advocate, navigator]      # User needs vs. market positioning
  - [strategist, operator]     # Long-term sequence vs. what ships now

bias_limit is the maximum number of consecutive turns any single agent can take before the orchestrator must rotate to another voice. Prevents any agent from dominating the conversation.

constraints:
  time:
    min_minutes: 2              # Minimum session duration
    max_minutes: 10             # Hard timeout
  budget:
    min: 1.00                   # Minimum spend before wrap-up allowed
    max: 10.00                  # Hard budget cap (triggers wrap-up)
    currency: USD
  rounds:
    min: 2                      # Minimum deliberation rounds
    max: 8                      # Maximum rounds before forced synthesis

All three constraint types work together. The session ends when any max value is reached. The orchestrator cannot wrap up until all min values are met.

Execution profiles can link to a workflow definition that specifies ordered steps, review gates, and artifact flow.

# In profile.yaml:
workflow: cto-execution-workflow    # Links to workflow YAML by ID

The workflow YAML defines the execution pipeline:

schema: aos/workflow/v1
id: cto-execution-workflow
name: CTO Execution Workflow

steps:
  - id: requirements
    name: Requirements Analysis
    action: targeted-delegation
    agents: [advocate, strategist]
    prompt: "Analyze the brief and extract structured requirements"
    input: []
    output: requirements_analysis
    review_gate: true

  - id: design
    name: Architecture Design
    action: targeted-delegation
    agents: [architect]
    prompt: "Design the architecture based on requirements"
    input: [requirements_analysis]
    output: architecture_decision
    review_gate: true

  - id: review
    name: Architecture Review
    action: tension-pair
    agents: [architect, operator]
    prompt: "Review architecture for buildability"
    input: [architecture_decision]
    output: revised_architecture

  - id: tasks
    name: Task Breakdown
    action: targeted-delegation
    agents: [operator]
    prompt: "Break the plan into engineering tasks with estimates"
    input: [revised_architecture]
    output: task_breakdown

  - id: risk
    name: Risk Assessment
    action: targeted-delegation
    agents: [sentinel]
    prompt: "Review for security, reliability, maintainability risks"
    input: [revised_architecture, task_breakdown]
    output: risk_assessment

  - id: stress-test
    name: Stress Test
    action: targeted-delegation
    agents: [provocateur]
    prompt: "Challenge the timeline, find gaps, stress-test assumptions"
    input: [revised_architecture, task_breakdown, risk_assessment]
    output: stress_test_findings

  - id: synthesize
    name: Final Assembly
    action: orchestrator-synthesis
    prompt: "Assemble the complete execution package"
    input: [requirements_analysis, revised_architecture, task_breakdown, risk_assessment, stress_test_findings]
    output: execution_package

gates:
  - after: requirements
    type: user-approval
    prompt: "Do these requirements look right?"
    on_rejection: retry_with_feedback

  - after: design
    type: user-approval
    prompt: "Does this architecture look right?"
    on_rejection: retry_with_feedback

Each step defines:

• action — targeted-delegation (send to specific agents), tension-pair (two agents debate), or orchestrator-synthesis (orchestrator assembles final output)
• input — Output IDs from previous steps that feed into this step
• output — Named output artifact produced by this step
• review_gate — If true, the user can approve or reject before proceeding

role_override in the profile's assembly.perspectives entries specializes agents for the workflow. The same Architect agent writes design docs in one profile and reviews code in another.

The output.format field determines the structure of the profile's deliverable.

path_template uses variables to generate the output path:

path_template: "output/memos/{{date}}-{{brief_slug}}-{{session_id}}/memo.md"

Available template variables: {{date}}, {{brief_slug}}, {{session_id}}, {{profile_id}}.

sections lists the named sections included in the output:

sections:
  - ranked_recommendations
  - agent_stances
  - dissent_and_tensions
  - tradeoffs_and_risks
  - next_actions
  - deliberation_summary

artifacts lists additional outputs (diagrams, structured data):

artifacts:
  - type: diagram              # Mermaid architecture diagram
  - type: task_list            # Structured task breakdown

Execution profiles differ from deliberation in several key ways.

Targeted delegation. The orchestrator sends specific tasks to specific agents rather than broadcasting. The CTO Orchestrator knows that Architect produces design docs and Operator produces task breakdowns — it delegates accordingly.

Ordered workflow. Steps execute in sequence. Each step's input references outputs from previous steps, creating a dependency chain. The orchestrator manages this flow automatically.

Review gates. The gates section defines user-approval checkpoints. When the workflow reaches a gate, it pauses and presents the output to the user:

gates:
  - after: requirements
    type: user-approval
    prompt: "Do these requirements look right?"
    on_rejection: retry_with_feedback

retry_with_feedback means the user can type feedback when rejecting, and the step re-runs with that feedback injected into the agent's prompt. This creates a human-in-the-loop refinement cycle.

role_override specialization. Execution profiles use role_override to repurpose general agents for specific tasks:

perspectives:
  - agent: architect
    required: true
    role_override: "Produce architecture decision records and system design docs"
  - agent: strategist
    required: true
    role_override: "Sequence the work into phases with dependency mapping"
  - agent: operator
    required: true
    role_override: "Break phases into concrete engineering tasks with effort estimates"
  - agent: sentinel
    required: true
    role_override: "Review all outputs for security, reliability, and maintainability risks"