Neutral Agent Card — Spec v1.0 (DRAFT)

The portable definition of a specialist. Runtime-agnostic: any agent runtime (opencode here, a standalone server, an Odoo-side runner) can interpret a card. This is the "Docker model": the format is neutral, the runtime ships or is preinstalled per target.

File

One JSON file per agent in agents/.

Schema

{
  "schema_version": "1.0",
  "agent_id": "o1-sellers-recruiter",
  "name": "Seller Recruiter",
  "role": "specialist",
  "description": "Finds and recruits consignment sellers for O1 on OLX and local forums",
  "model_hint": "free-tier",
  "persona": "Practical Bulgarian business developer; direct, trustworthy; works in BG+EN",
  "prompt_files": ["prompts/sellers-recruiter.md"],
  "tools": ["odoo.search_records", "odoo.create_record", "file.read", "script.run"],
  "memory": {
    "engine": "brain",
    "script": "brain/brain.py",
    "namespace": "o1-sellers"
  },
  "gates": ["hours"],
  "verification": {
    "definition_of_done": "Confirmed N sellers recruited with signed consignment agreements this cycle",
    "check": "odoo.search_records('o1.seller', [['status','=','signed']]).count >= N"
  }
}

Field rules

model_hint is a class (free-tier / balanced / max), never a concrete vendor model ID. Each runtime maps hints to its own models (here: free-tier → opencode/mimo-v2.5-free).
tools are declared by name against a shared tool registry — no inline code in cards. The runtime resolves names to implementations.
prompt_files keep prompts external (markdown) — cards stay data.
memory points to a brain script + namespace; the card never carries memory content.
verification is mandatory — a machine-checkable definition of done. A card without one is rejected by the validator. ("I processed X" is never done; "I confirmed X exists/counts" is done.)
gates are named constraints (working hours, irreversible-action gate) resolved by the runtime.
No runtime-specific syntax, no absolute paths, no secrets.

Mapping: neutral card ↔ opencode agent

The converter is a small script; both directions must round-trip losslessly (convert → back → identical hash).

Neutral card field	opencode agent (`agent/*.md` frontmatter / body)
`description`	frontmatter `description`
`model_hint`	frontmatter `model` (resolved via model map)
`tools`	frontmatter tool booleans (`write: true`, `bash: true`, ...)
`prompt_files`	body / loaded instructions
`memory`	brain.py reference in body
`verification`	"Completion Verification" section in body
`gates`	body constraints section

Validator

validate-depo.sh rejects a package when: any card is missing a field, verification is absent, prompt_files referenced but missing, tools named but unregistered in the tool registry, or secrets detected.

2.9 KiB Raw Blame History