# 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

```json
{
  "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

1. **`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`).
2. **`tools`** are declared by *name* against a shared tool registry — no
   inline code in cards. The runtime resolves names to implementations.
3. **`prompt_files`** keep prompts external (markdown) — cards stay data.
4. **`memory`** points to a brain script + namespace; the card never carries
   memory content.
5. **`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.)
6. **`gates`** are named constraints (working hours, irreversible-action gate)
   resolved by the runtime.
7. 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.