Skip to content
Verticla

Every Verticla agent reads five plain-text Markdown files at boot, composed into the agent's system context: SOUL.md, AGENTS.md, USER.md, TOOLS.md, and HEARTBEAT.md. The five files are the lineage from the OpenClaw control-file pattern. Pods edit them directly through git, fork them per user, and own the agent's behavior the same way they own their codebase. There is no prompt-engineering UI, no JSON config, no opaque settings page.

TL;DR

  • Five files, plain Markdown — SOUL, AGENTS, USER, TOOLS, HEARTBEAT
  • Edited through git — versioned, reviewable, auditable, rollback-able
  • Templates per pack — every pack ships starter files; pods fork per pod or per user
  • Composed at boot — entrypoint concatenates the five into ~/.claude/CLAUDE.md before Claude Code starts
  • Lineage — adopted from the OpenClaw control-file pattern, generalized to the Verticla architecture

What does each file do?

SOUL.md — identity and operating principles

The agent's personality. What it cares about, how it talks, what it refuses to do, what its non-negotiables are. Two paragraphs to a page. Loaded first so every downstream prompt is shaped by it.

Example excerpts a real-estate pack SOUL.md might contain:

  • "I work for , a buyer's agent in . My job is to surface the right buyer-listing matches in time for action, never after."
  • "I never recommend an offer without a CMA range. If I don't have comps, I say so."
  • "I write in 's voice. If I'm not sure of the voice, I ask before sending."

AGENTS.md — the rest of the pod

What other agents in the pod do, what their tools are, when to delegate to them, how to format a handoff. The map for cross-agent coordination via the coordination plane.

Example excerpt:

  • "Teammate Sarah's agent runs CMAs and pricing strategy. When I need a price recommendation, I post to the plane via pod_post_artifact with kind: 'cma_request' and let her agent claim it."
  • "Teammate Mike's agent handles transaction coordination. Once a deal goes pending, I hand off to Mike's agent with the contact + deal IDs."

USER.md — the human teammate this agent reports to

The single source of truth about the user the agent is acting on behalf of. Voice samples, schedule, working hours, communication preferences, role boundaries. Pulls from the pod admin's onboarding flow and is editable by the user.

Example fields:

  • name, role, pronouns
  • working_hours, time_zone, do_not_disturb_blocks
  • voice_samples — three to five recent emails the agent uses to learn the user's writing voice
  • decision_authority — what the agent can act on autonomously vs what requires user confirmation

TOOLS.md — the MCP tools available and when to use them

A guide for the agent on which MCP tool to reach for in which situation. Each pack ships a default TOOLS.md reflecting the pack's tool design intent; pods can edit to add per-pod conventions.

Example:

  • "When the user asks 'who should I follow up with?', call inbox_check_thread first to see recent activity, then contacts_search filtered to last_touch > 7 days."
  • "Never call cma_advisor without first confirming the subject address with the user."
  • "When the user says 'add this listing', use listings_create from the real-estate pack — not documents_save_version."

HEARTBEAT.md — autonomous schedule for off-hours work

What the agent does on its own when no user is in session. Cron-style schedule with task descriptions. The agent runs these in the background via the auto-save loop.

Example:

  • "Every weekday at 6 AM local: review yesterday's outcomes, recalibrate behavior weights via the real-estate pack's outcomes_recompute tool."
  • "Every Sunday at 8 PM: pull the pod's coming-week calendar, draft a Monday-morning brief for the user."
  • "Every 4 hours during working hours: scan new listings, run buyer-match against active buyers, post promising matches to the coordination plane for the user's morning review."

How does a pod edit these?

The pod's workspace is a git repo. The control files live in:

.claude/
  SOUL.md
  AGENTS.md
  USER.md
  TOOLS.md
  HEARTBEAT.md

(The agent reads them from /home/agent/.claude/CLAUDE.md, which the entrypoint composes from the five files at boot.)

Editing flow:

  1. Pod member opens their workspace in the agent's terminal pane (or any git client)
  2. Edits the relevant .md file
  3. Commits the change to the pod's workspace branch
  4. Next agent session picks up the new file at boot

Edits are auditable through git log. Rollbacks are git revert. The pod owns the history.

Where do templates come from?

Every pack ships starter templates. When a pack is enabled, the platform copies the pack's templates into the pod's workspace if no pod-specific version exists. The pod then customizes from there.

Pack template paths:

verticals/<pack>/control-files/
  SOUL.md.tpl
  AGENTS.md.tpl
  USER.md.tpl
  TOOLS.md.tpl
  HEARTBEAT.md.tpl

Templates use Mustache-style placeholders ({{user.name}}, {{pod.market}}, etc.) that the entrypoint fills at boot from the user's profile and pod settings.

Why plain text and not a UI?

Three reasons:

  1. Editability matches the team's existing workflow. The 2-15 person teams Verticla serves already use git for code, docs, or both. Adding a UI for agent prompt-engineering would be a learning curve. Editing Markdown in a git repo is not.
  2. Auditability is free. Git is the audit log. No additional tracking infrastructure needed.
  3. Forking is trivial. A pod-wide template can be customized per user with a git checkout -b and a few edits. Templating systems with branching factors built into the UI either constrain the customization or balloon the UI complexity.

A UI may eventually layer on top for non-technical pod members. The plain-text-in-git substrate is the source of truth in either case.

What about secrets in control files?

Control files are not the right place for secrets. The Anthropic API key, OAuth credentials for the comms pack, and any other sensitive credentials live in the pod's encrypted credential store and are injected as env vars at container spawn. Control files reference them by name ({{pod.comms.slack_oauth}}) but never contain the value.

The platform's pre-commit hook (in the pod's workspace template) blocks commits that look like they contain credential strings.

How does this differ from the OpenClaw original?

OpenClaw introduced the five-file control-file pattern for solo agent operators. Verticla generalizes it to multi-user pods:

  • AGENTS.md is no longer a static description; it references real teammates' agents reachable via the coordination plane
  • USER.md is one of N — every pod member has their own
  • Templates ship per pack, not per agent
  • The audit + governance layer that wraps the files is platform-managed (admin surface, RBAC, version pinning)

The shape of the files is unchanged. Pods migrating from OpenClaw can drop their existing files into a Verticla workspace with minor edits to AGENTS.md.