Skip to content

There are two types of agent-related files in a workspace, aimed at different roles:

FileAudiencePurpose
AGENTS.md (workspace root)UsersProject description — tells agents what this project is about
.openharness/agents/*.mdDevelopersAgent behavior definitions — configures roles, models, tool permissions, switching rules

AGENTS.md — User-Authored Project Description

Section titled “AGENTS.md — User-Authored Project Description”

AGENTS.md lives at the workspace root. It is a project context document for agents. It does not control agent behavior — it provides background information.

The runtime injects the full text of AGENTS.md into the system prompt (no summarization or trimming), so agents understand the current project.

What to write:

  • Project goals and background
  • Directory structure
  • Coding conventions
  • Build, test, and deploy commands
  • Common pitfalls

What not to write:

  • Structured config DSLs
  • Permission rules
  • Executable process definitions

tip

Think of `AGENTS.md` as "an onboarding doc for a new teammate," not a config file.

.openharness/agents/*.md — Developer-Defined Agent Behavior

Section titled “.openharness/agents/*.md — Developer-Defined Agent Behavior”

Agents are defined in .openharness/agents/*.md using Markdown with YAML frontmatter. These files are authored by developers and control how each agent behaves:

  • Filename is the agent name (e.g., builder.md -> agent name builder)
  • YAML frontmatter carries structured config
  • Markdown body is the main system prompt
  • If a workspace agent shares a name with a platform built-in agent, the workspace agent wins
---
mode: primary
description: Implement requested changes in the current workspace
model: default
system_reminder: |
You are now acting as the builder agent.
Focus on making concrete code changes.
tools:
native:
- Bash
- TerminalOutput
- TerminalInput
- TerminalStop
- Read
- Write
- Edit
- Glob
- Grep
actions:
- code.review
skills:
- repo.explorer
external:
- docs-server
switch:
- plan
subagents:
- code-reviewer
policy:
max_steps: 40
run_timeout_seconds: 1800
---
# Builder
You are a pragmatic software engineering agent.
Prefer making concrete progress in the current workspace.
FieldRequiredDescription
modeNoprimary, subagent, or all. Default: primary
descriptionNoShort description of the agent
modelRecommendedModel alias or direct model reference
system_reminderNoReminder injected after agent switch
toolsNoAllowlist of native tools, actions, skills, external tools
switchNoAgents this agent can switch to within a run
subagentsNoAgents this agent can delegate to
policyNoStep limits, timeouts, concurrency constraints

mode semantics:

ValueDescription
primaryCan be the session’s main agent or a switch target
subagentPrimarily a delegation target; not recommended as a switch target
allCan serve as both primary and subagent (use with caution)

Fields not placed in frontmatter: name (redundant with filename), context (runtime-assembled), hooks (runtime extension).

  • The Markdown body is the main system prompt; the runtime preserves it as-is
  • An empty body is treated as an incomplete definition
  • Supports Chinese and other Unicode characters
  • Native tools use Title Case: Bash, TerminalOutput, Read, TodoWrite
model: default
FieldDescription
modelAlias declared in settings.yaml -> models; direct model_ref is also accepted for compatibility

The runtime resolves model to a concrete model_ref during load. Model parameters such as temperature, top_p, and max_tokens should be configured under settings.yaml -> models.<alias>. Legacy model: { alias: ... }, model_ref, and frontmatter-level model params are still accepted for compatibility.

model is the only recommended-required structured field in frontmatter.

tools:
native:
- Bash
- TerminalOutput
- TerminalInput
- TerminalStop
- Read
actions:
- code.review
skills:
- repo.explorer
external:
- docs-server
Sub-fieldDescription
nativeBuilt-in tools
actionsWorkspace actions
skillsWorkspace skills
externalMCP tool servers
  • native must be explicitly declared; omitted native exposes no built-in tools
  • Omitted external, actions, and skills inherit the default capabilities discovered in the current workspace
  • An explicit empty array disables that capability class, for example external: [] does not fall back to default MCP servers
  • Expresses an allowlist only, not execution logic
  • Parsed uniformly from the workspace declaration
switch:
- plan
- build
  • Each entry is a target agent name; target should be mode: primary or mode: all
  • Without switch, the agent cannot initiate switches
  • The runtime validates targets against this list before executing agent.switch
subagents:
- repo-explorer
- code-reviewer
  • Each entry is a subagent this agent can delegate to; target should be mode: subagent or mode: all
  • Without subagents, the agent cannot delegate
  • The runtime validates targets before executing agent.delegate
  • Availability is determined by workspace declarations and runtime configuration
policy:
max_steps: 40
run_timeout_seconds: 1800
tool_timeout_seconds: 120
parallel_tool_calls: true
max_concurrent_subagents: 3
FieldDescription
max_stepsMaximum reasoning steps
run_timeout_secondsTotal run timeout
tool_timeout_secondsPer-tool execution timeout
parallel_tool_callsWhether to allow parallel tool calls
max_concurrent_subagentsMaximum concurrent subagents; unlimited when omitted

Do not add complex routing, retry logic, or conditional expressions to policy.

A reminder segment injected when switching agents.

Injection triggers:

  • AgentSwitch within the same run
  • First message after the user manually updates activeAgentName

Injection format:

<system_reminder>
{standard switch prompt + agent.system_reminder}
</system_reminder>
RuleDetails
LocationLatest user message, not the system prompt
FrequencyOnce after switch; not repeated on subsequent turns
On session creationNot injected
Content suggestionsRole switch reminders, boundary notes, tool preferences
---
mode: primary
description: Analyze tasks and create implementation plans
model: default
tools:
native:
- Read
- Glob
- Grep
switch:
- build
---
# Planner
Analyze the user's request, explore the codebase,
and produce a clear implementation plan. When ready,
switch to the builder agent.
---
mode: primary
description: Implement changes in the workspace
model: default
tools:
native:
- Bash
- TerminalOutput
- TerminalInput
- TerminalStop
- Read
- Write
- Edit
- Glob
- Grep
switch:
- plan
subagents:
- reviewer
policy:
max_steps: 40
---
# Builder
Make concrete code changes based on the plan.
When done, delegate to the reviewer for a code review.
---
mode: subagent
description: Review code changes
model: default
tools:
native:
- Read
- Glob
- Grep
---
# Reviewer
Review recent changes for bugs, style issues,
and missing edge cases. Return a structured review.
  1. User sends a message; session uses plan agent by default
  2. Planner analyzes the request and creates a plan
  3. Planner switches to build via agent.switch
  4. Builder implements code changes
  5. Builder delegates to reviewer via agent.delegate
  6. Reviewer reviews code in a child session and returns findings
  7. Builder applies fixes if needed and completes the run