# GBDL Specification v0.1

**GrokBot Definition Language** is a community proposal for an open, portable format that describes a multi-agent desktop assistant setup as one Markdown file. It is not an official Grok Bot product format.

A GBDL document lets you save bot persona, required account connectors, onboarding steps, user context (non-secret), named agents with routines, optional channels, skills, and routing hints. Tools can parse the file and reinstantiate the fleet: ask for connectors first, run onboarding, create agents, write memory, and attach routines.

Version: `0.1`  
Canonical extension: `.gbdl.md`  
License: MIT (see `LICENSE`)

---

## 1. Document shape

A GBDL file is Markdown with:

1. An optional short human-readable intro (title, blurb, notes for people).
2. Exactly one fenced YAML block using the language tag `yaml`.

Tools ignore prose outside that fence and parse only the YAML object inside it.

Example layout (illustrative):

    # My Ops Fleet
    Short intro for humans.

    ```yaml
    gbdl: "0.1"
    meta:
      name: example
    # ...
    ```

### Rules

- There must be exactly one fenced block tagged `yaml` that contains the definition.
- Nested fences inside the YAML value (for example, skill bodies) are not supported in v0.1; keep skill bodies as plain strings.
- YAML must be a single mapping (object) at the top level.
- Encoding: UTF-8.
- Secrets (API keys, tokens, passwords, session cookies, private keys) must never appear in the file.

---

## 2. Top-level keys

| Key | Required | Type | Purpose |
|-----|----------|------|---------|
| `gbdl` | yes | string | Spec version. Must be `"0.1"` for this document. |
| `meta` | yes | object | Package identity for humans and catalogs. |
| `bot` | yes | object | Root dispatcher / main assistant persona. |
| `connectors` | yes | array | Account connectors to request before agents run. |
| `onboarding` | yes | array | Ordered setup steps after connectors. |
| `user_context` | yes | object | Non-secret profile lines and memories. |
| `agents` | yes | array | Named specialist agents to create. |
| `channels` | no | array | Named groups of agents. |
| `skills` | no | array | Reusable skill documents. |
| `routing` | no | object | Intent string to agent name map. |

Unknown top-level keys should be ignored by parsers (forward compatibility) but may be rejected by strict validators.

---

## 3. Field reference

### 3.1 `meta`

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | yes | string | Short slug or display name of this definition package. |
| `description` | yes | string | One or two sentences on what the fleet does. |
| `author` | no | string | Person or org; avoid private contact details. |
| `tags` | no | array of strings | Free-form labels (`ops`, `media`, `inbox`). |

### 3.2 `bot`

The dispatcher persona: the primary assistant users talk to first.

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | yes | string | Bot handle or short name. |
| `title` | no | string | Optional display title. |
| `description` | yes | string | Persona, scope, and how it delegates. |

### 3.3 `connectors`

Ordered list of account connectors the host should prompt for (connect cards) before creating agents or writing memories that depend on those accounts.

Each item:

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `id` | yes | string | Stable machine id (`gmail`, `notion`, `slack`). |
| `label` | yes | string | Human label on the connect card. |
| `required` | yes | boolean | If true, onboarding should not proceed without it. |
| `accounts` | no | array of strings | Hints such as `work`, `personal`, or fictional labels. |
| `notes` | no | string | Guidance for the user (scopes, which inbox). |

Connectors name *kinds* of integration, not credentials. Credentials stay in the host's secret store.

### 3.4 `onboarding`

Ordered steps shown after connectors are satisfied (or optional ones skipped).

Each step is either:

- a plain string (instruction text), or
- an object:

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `id` | no | string | Stable step id. |
| `title` | no | string | Short title. |
| `instruction` | yes (if object) | string | What the user or host should do. |

### 3.5 `user_context`

Non-secret context seeded into the bot/agent memory layer.

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `profile` | yes | array of strings | Stable facts (role, prefs, timezone labels). |
| `memories` | yes | array of strings | Working memories or standing instructions. |

Both arrays may be empty. Do not put secrets, tokens, or private third-party personal data here. Use fictional or generic examples in shared files.

### 3.6 `agents`

Specialist agents created during reinstantiation.

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | yes | string | Unique within the file. Used by channels and routing. |
| `description` | yes | string | Role, tools, boundaries. |
| `section` | no | string | UI grouping (`Inbox`, `Workspace`, `Creative`). |
| `seed_message` | no | string | First message or system nudge after create. |
| `routines` | no | array | Scheduled or triggered jobs (see below). |

#### Routines

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | yes | string | Routine label. |
| `schedule` | no | string | Human or cron-like schedule (`weekdays 9am local`). |
| `trigger` | no | string | Event trigger (`new_email`, `slash:/standup`). |
| `prompt` | yes | string | What the agent should do when the routine fires. |

At least one of `schedule` or `trigger` should be present for a routine to be actionable; validators may warn if both are absent.

### 3.7 `channels` (optional)

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | yes | string | Channel label. |
| `members` | yes | array of strings | Agent `name` values that must exist in `agents`. |

### 3.8 `skills` (optional)

Portable skill docs the host may attach to agents or the bot.

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `name` | yes | string | Skill id / title. |
| `description` | yes | string | When to use it. |
| `body` | yes | string | Full skill text (Markdown allowed as a string). |

### 3.9 `routing` (optional)

Map of intent keys to agent names for the dispatcher.

```yaml
routing:
  inbox_triage: Email Inbox
  docs: Workspace
```

Values must match an `agents[].name`. Keys are free-form intent labels.

---

## 4. Reinstantiation semantics

Hosts that "load" a GBDL file should follow this order unless the user overrides it.

1. **Validate** the YAML against this spec (and optionally `schema/gbdl-0.1.schema.json`).
2. **Connectors first.** Present connect cards for each entry in `connectors`, required ones blocking. Do not create agents that need a missing required connector.
3. **Onboarding.** Walk `onboarding` in order. Record completion in host state, not back into the GBDL file unless the user exports again.
4. **Bot.** Ensure the root bot exists with `bot.name` / `bot.description` (and `title` if present).
5. **User context.** Write `user_context.profile` and `user_context.memories` into memory as non-secret entries. Never treat them as credentials.
6. **Agents.** For each agent, call the host's create-agent flow with name, description, section, and optional seed message.
7. **Routines.** Attach each routine to its agent (schedule and/or trigger + prompt).
8. **Channels.** Create or update channels and membership from `channels`.
9. **Skills.** Install or register skills; binding to specific agents is host-defined in v0.1.
10. **Routing.** Apply `routing` so the dispatcher can hand off by intent.

Idempotency: re-loading the same file should update or skip existing agents by name rather than blindly duplicating, when the host supports upsert.

Export: hosts may reverse the process (agents, connectors list without secrets, memories marked exportable) into a new `.gbdl.md`. Strip secrets on export.

---

## 5. Validation rules

### Hard errors (must reject)

- Missing `gbdl` or value not equal to `"0.1"` (for v0.1 tools).
- Missing required keys: `meta`, `bot`, `connectors`, `onboarding`, `user_context`, `agents`.
- `meta.name`, `meta.description`, `bot.name`, `bot.description` empty.
- `connectors` item missing `id`, `label`, or `required`.
- `agents` item missing `name` or `description`.
- Duplicate `agents[].name`.
- `channels[].members` referencing an unknown agent name.
- `routing` value referencing an unknown agent name.
- `user_context` missing `profile` or `memories` (empty arrays are OK).
- More than one YAML fence intended as the definition (if detectable), or zero YAML fences.
- Detectable secret patterns in any string field (host-defined heuristics; at minimum reject keys named like `api_key`, `password`, `token` as YAML map keys under the definition).

### Soft warnings (may accept)

- Routine with neither `schedule` nor `trigger`.
- Empty `agents` array (valid but useless).
- Optional connector never connected.
- Unknown top-level keys.
- `author` looks like an email (prefer names only in shared catalogs).

### Privacy

- No real personal emails, phones, government ids, or private CRM/fundraising data in examples or shared definitions.
- Prefer fictional names (e.g. Alex Rivera, Northwind Media) and `example.com`.
- Connectors declare *that* an account is needed, not *how* to authenticate in-file.

---

## 6. Conformance

A document is **GBDL 0.1 conformant** if:

1. It is Markdown containing exactly one parseable `yaml` fence whose root object satisfies the hard validation rules above, and
2. Reinstantiation can proceed connectors-first without reading secrets from the file.

A host is **GBDL 0.1 compatible** if it can parse such a file, prompt for listed connectors, and create the declared bot, agents, context, and routines according to section 4.

---

## 7. Versioning

- `gbdl: "0.1"` pins this schema.
- Additive optional keys may appear in later 0.x drafts; strict older parsers ignore unknowns.
- Breaking changes require a new `gbdl` version string and a new schema file.

---

## 8. Examples

See `examples/` in this repository:

- `minimal.gbdl.md` - smallest useful fleet
- `ops-team.gbdl.md` - dispatcher plus inbox / workspace / Notion-style agents
- `media-studio.gbdl.md` - fictional creator / media ops fleet

---

## 9. Status

GBDL v0.1 is a **community proposal / open format**. It is not affiliated with or endorsed as an official Grok Bot product specification. Feedback and compatible tools are welcome via the project repository.