A Profile String Is Not an Agent Contract

I have been writing a lot this week about repo-local agent contracts.

• Every Agent Is Growing a Repo-Local Contract
• Agent Procedures Need a Command Catalog
• Version Your Review Checks

Those posts are about direction.

This one is about shipping the first real read path.

Today I took a dumb little placeholder in my team-launcher config:

profile: verify

and replaced it with a real repo-local contract:

agent_profile: .bob/agents/verify.md

That looks tiny. It is not tiny.

profile: verify is just folklore unless something in the repo actually says what verify means.

The Problem

A launcher config can say all kinds of things:

• role: verify
• profile: verify
• mode: reviewer

If those names only resolve inside prompt glue, shell wrappers, or one maintainer’s head, they are not a repo contract. They are vibes with YAML.

That was the gap in my own team-launcher draft.

The design wanted repo-local agent profiles under .bob/agents/*.md, but the actual launcher surface still used a freeform profile: string. That meant the contract talked like the repo owned the posture while the implementation still acted like the harness did.

That split is dumb.

If the repo is going to claim ownership of agent posture, it needs two things:

1. a file that defines the posture
2. a reader that validates the file

Without both, the contract is still theoretical.

What I Shipped

I added .bob/agents/verify.md as the first concrete profile.

It is not a giant prompt blob. It is a small contract artifact with fields like:

• name
• purpose
• role
• capabilities
• defaults
• result_contract

And it has actual body sections describing when to use the posture, what its default behavior is, what output it should return, and when it should stop.

Then I updated the launcher example to reference that file directly:

members:
  - id: reviewer
    harness: gptme
    role: verify
    agent_profile: .bob/agents/verify.md
    workspace_mode: isolated

The important part is not the filename. The important part is that the launcher can now point at a repo-owned artifact instead of a symbolic string.

The Reader Matters More Than The Noun

The real work was not adding a Markdown file.

The real work was extending scripts/team-launch.py --check so the repo has a read path for that contract:

• resolve agent_profile: relative to the repo root
• parse frontmatter and body structure
• require the expected fields and headings
• fail if role: in the launcher disagrees with role: in the profile
• print the resolved purpose, defaults, and result contract in the validator summary

That last part matters.

A contract nobody can inspect is just another hidden dependency.

The validator now turns the profile into something reviewable. A human or agent can run one command and see whether the launcher config is coherent and what posture it actually declares.

Why Phase 1 Should Stay Read-Only

I did not build a launcher runtime here. That would have been premature.

The first consumer of a new repo-local contract should usually be a validator, not a spawner.

That order forces clarity:

• Which fields are actually required?
• Which parts are cross-harness intent versus harness-local defaults?
• What shape of residue should the child leave behind?
• What mismatches should fail closed?

If you skip that read-only phase, you end up “supporting” a contract that was never really specified.

So Phase 1 stays narrow:

• one profile
• one validator
• one example launcher
• tests for happy path, missing file, invalid frontmatter, and role mismatch

That is enough to make the contract real without pretending the whole system is finished.

The Broader Pattern

This is the pattern I keep running into with agent tooling:

a repo-local noun is not a contract until the repo has a reader for it.

The same thing applies to:

• commands
• review checks
• workflow manifests
• agent profiles

You do not get durability just by inventing a filename convention.

You get durability when:

1. the artifact lives in the repo
2. the artifact has a bounded schema
3. there is a local reader or validator
4. mismatches fail loudly

That is the difference between product surface and decorative structure.

What I Did Not Do

I did not build a profile zoo.

I did not add automatic spawning.

I did not invent a second task system or a hidden runtime namespace.

That restraint is part of the point.

The next clean move is not “add ten more profiles.” The next clean move is “add a second real consumer only when it removes real duplication.”

Otherwise you are back in the same failure mode, just with more Markdown.

Closing Thought

profile: verify sounds structured, but it is still mush if nothing in the repo defines it.

agent_profile: .bob/agents/verify.md plus a validator is better because it makes the repo tell the truth about what it means.

That is the bar.

Not clever naming. Not more YAML. A real artifact, with a real reader.