Envelope Migration

Since v2026.8.4, public Agent, Team, and Flow YAML is flat. The file is the agent: a name, a prompt, the tools. There is no apiVersion / kind / metadata / spec wrapper.

Old envelopes still load and run. You get one warning that points here. Nothing is renamed on disk until you convert.

kind: Service and kind: TestSuite stay enveloped. Filenames stay (role.yaml, flow.yaml). New agents default to agent.yaml.

Convert a file or folder

initrunner doctor --fix PATH [--yes] [--no-backup] [--force]

PATH may be a file or a directory. The rewriter:

• Converts Agent, Team, and Flow YAML in place
• Writes PATH.bak unless you pass --no-backup
• Skips files that are already flat, plus Service and TestSuite documents
• Refuses when a rewrite would change behavior (for example a Flow whose metadata.name is not kebab-case)
• Requires --yes when stdin is not a TTY
• Overwrites an existing .bak only with --force

Before

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: web-searcher
spec:
  role: Search the web and cite sources.
  model:
    provider: openai
    name: gpt-5-mini
  tools:
    - type: search

After

name: web-searcher
model: openai:gpt-5-mini
prompt: Search the web and cite sources.
tools:
  - search

Composed documents use agents, run, then, and after (startup order). personas is not a public word. Since v2026.8.6 a composed document whose members are all bare use: references is a group of independent agents rather than a sequential team.

A bare tool name (- search) enables defaults. A mapping adds options (- filesystem: {root_path: .}).

What still works

• Existing envelope files execute unchanged
• initrunner run . prefers agent.yaml, then role.yaml, then a single flat or envelope document in the directory
• initrunner new, templates, flow new, the dashboard builder, and imports write only flat YAML (spec_version: 3)

Two follow-ups landed in v2026.8.5:

• The model-driven generators behind initrunner new, --langchain, and --pydantic-ai were still asking for the old envelope, so a freshly generated agent was born deprecated. All three now describe the flat shape and spec_version: 3.
• Validation issues were labelled with paths like spec.role and spec.tools, which the flat schema rejects. They now name the flat field. The flow and group member path is agents.<name>.use.

See Doctor for the full --fix flag set, and Configuration for the flat schema.