docs: frozen v1.0 bundle format specs (manifest, agent-card, o1 package structure)

2026-08-03 19:56:51 +03:00
commit e2f76e4027
4 changed files with 221 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 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.