Strategy File Format
Schema reference for strategy files — agent definitions, flow definitions, steps, and nesting.
A strategy file is a JSON or YAML document with three top-level fields: name, version, and the orchestration graph (agents + flow). The schema is validated at load time with Zod.
Strategy
The top-level strategy type.
Prop
Type
Agent Definitions
The agents field is a map of named agent definitions. Each agent is a user agent, an LLM agent, or a registered custom agent. The type field discriminates between them — user agents set type: "user", LLM agents may omit type, and custom agents use their registered type name.
LLMAgentDef
An LLM agent references a model by string (e.g. "openai/gpt-4o"), resolved via the global model/provider registry at load time. Tools are referenced by string name from the tool registry.
Prop
Type
Example:
agents:
coder:
model: openai/gpt-4o
systemPrompt: You are a coding assistant.
tools:
- read_file
- glob
- search_files
providerOptions:
openai:
reasoningEffort: high
modelOptions:
temperature: 0.3
maxOutputTokens: 2048
outputSchema:
type: object
properties:
summary:
type: string
required: [summary]
context:
rollingWindow: 40
compaction:
keepRecent: 8providerOptions configures provider-specific features such as extended thinking or reasoning effort. modelOptions configures provider-independent generation parameters such as temperature, maxOutputTokens, topP, and seed. outputSchema accepts a JSON Schema object for structured output. context controls rolling-window and compaction behavior for conversation history. See createAgent for details.
UserAgentDef
A user agent collects input from a human. Set requireInput: true to block until input is provided, or use presetMessage for a fixed message.
Prop
Type
Example:
agents:
user:
type: user
description: Collects the user's question.
config:
requireInput: trueAgentDef
The union of all agent definition types.
Prop
Type
CustomAgentDef
A custom agent references a type registered by a project entry or a file in comma-project.json's agents array. Put implementation-specific fields inside config:
agents:
echoer:
type: prefixed-echo
description: Adds a prefix without calling a model.
config:
prefix: "Echo: "Prop
Type
The project must register prefixed-echo before the strategy loads. See createAgent for the TypeScript registration API.
Flow Definitions
The flow field defines the entry flow — a tree of steps that can reference agents or nest sub-flows. Flow type is discriminated by the type field.
FlowDef
The union of all flow definition types.
Prop
Type
SequentialFlowDef
Runs steps one after another. Each step receives the previous step's output as its input.
Prop
Type
CycleFlowDef
Repeats steps for a fixed number of cycles or until stopped when cycles is "Infinity". An observer can approve the current step output or return feedback for the next cycle.
Prop
Type
For observer-driven loops, use a unique first-line break token so ordinary prose cannot end the cycle accidentally:
name: refine-until-approved
type: cycle
cycles: "Infinity"
observer: reviewer
breakCycleSignals: ["==APPROVED=="]
breakCycleSignalMatch: first-line
steps:
- agent: writerWhen the observer emits ==APPROVED== on its first non-empty line, the cycle returns the last step output. Otherwise, the observer's response becomes the input to the next cycle.
BroadcastFlowDef
Runs all steps in parallel with the same input. Results are joined into a single output.
Prop
Type
CustomFlowDef
References a flow type registered by a project entry or a file in comma-project.json's flows array. Put implementation-specific fields inside config:
name: First Approved Review
type: first-match
steps:
- agent: reviewer-a
- agent: reviewer-b
config:
marker: APPROVEDProp
Type
The project must register first-match before the strategy loads. See Custom Flows for the TypeScript registration API.
Steps
Each entry in a flow's steps array is either an agent reference or a nested flow definition.
AgentStep
References a named agent from the agents map.
Prop
Type
Nested Flows
A step can be a full flow definition instead of an agent reference. This lets you compose complex orchestration graphs:
{
"name": "Research Pipeline",
"version": "1.0",
"agents": {
"researcher-a": { "model": "openai/gpt-4o", "systemPrompt": "Research from angle A." },
"researcher-b": { "model": "openai/gpt-4o", "systemPrompt": "Research from angle B." },
"summarizer": { "model": "openai/gpt-4o", "systemPrompt": "Summarize the research." }
},
"flow": {
"name": "Pipeline",
"type": "sequential",
"steps": [
{
"name": "Parallel Research",
"type": "broadcast",
"steps": [
{ "agent": "researcher-a" },
{ "agent": "researcher-b" }
]
},
{ "agent": "summarizer" }
]
}
}Here the sequential flow's first step is a broadcast sub-flow that runs two researchers in parallel, then pipes the combined output to the summarizer.
Full Examples
Sequential — Code Review
{
"name": "Code Review Pipeline",
"version": "1.0",
"description": "Analyzer identifies issues, reviewer suggests fixes.",
"agents": {
"analyzer": {
"model": "openai/gpt-4o",
"systemPrompt": "Examine the code and identify potential bugs and code smells. Output a numbered list (max 5)."
},
"reviewer": {
"model": "openai/gpt-4o",
"systemPrompt": "Read the analysis and provide specific, actionable suggestions to fix each issue."
}
},
"flow": {
"name": "Review Pipeline",
"type": "sequential",
"steps": [
{ "agent": "analyzer" },
{ "agent": "reviewer" }
]
}
}Cycle — Iterative Refinement
{
"name": "Iterative Refinement",
"version": "1.0",
"agents": {
"writer": {
"model": "openai/gpt-4o",
"systemPrompt": "Write or revise content based on the given topic or feedback."
},
"critic": {
"model": "openai/gpt-4o",
"systemPrompt": "Evaluate the content for clarity and engagement. Provide specific feedback."
}
},
"flow": {
"name": "Refinement Loop",
"type": "cycle",
"steps": [
{ "agent": "writer" },
{ "agent": "critic" }
],
"cycles": 3
}
}Broadcast — Parallel Research
name: Research Team
version: "1.0"
agents:
technical:
model: openai/gpt-4o
systemPrompt: >
Analyze the topic from a technical perspective.
Cover architecture, tools, and best practices.
business:
model: openai/gpt-4o
systemPrompt: >
Analyze the topic from a business perspective.
Cover market opportunities and ROI.
risk:
model: openai/gpt-4o
systemPrompt: >
Analyze the topic for potential risks and failure modes.
flow:
name: Parallel Research
type: broadcast
steps:
- agent: technical
- agent: business
- agent: riskAgent with Tools
name: Tool Agent
version: "1.0"
agents:
explorer:
model: openai/gpt-4o
systemPrompt: >
You are a coding assistant. Use the available tools to explore
the codebase and answer questions.
tools:
- read_file
- glob
- search_files
flow:
name: Explore
type: sequential
steps:
- agent: explorerTools are referenced by their registered name. Common built-ins include read_file, list_directory, search_files, glob, write_file, edit_file, and run_command. Custom tools must be registered via registerTool before loading the strategy.