Skip to content
This repository was archived by the owner on May 11, 2026. It is now read-only.

Commit 29b63b5

Browse files
claudeclaude
committed
feat(v2.0.0): add grok-swarm + grok-voice specs for Grok 4.20; audit existing schemas
Two new official YAML specs mapping 1:1 to Grok 4.20's multi-agent and voice APIs, plus non-breaking Grok 4.20 enum additions to four existing schemas, a 14-schema discovery manifest, and docs/ reference pages. New files: - specs/grok-swarm.yaml — annotated swarm orchestration reference spec - schemas/grok-swarm.schema.json — JSON Schema draft/2020-12 for grok-swarm - specs/grok-voice.yaml — annotated voice API reference spec - schemas/grok-voice.schema.json — JSON Schema draft/2020-12 for grok-voice - schemas/index.json — 14-schema discovery manifest (spec, schema_url, file_glob) - docs/index.md — 14-spec overview with VS Code snippet and CI notes - docs/grok-swarm.md — reference documentation for grok-swarm - docs/grok-voice.md — reference documentation for grok-voice Schema audits (non-breaking additive changes): - grok-agent.json: add grok-4.20, grok-4.20-multi-agent, grok-4.20-fast to model_override enum - grok-config.json: same additions to default_model and fallback_model enums - grok-security.json: add voice.read, voice.write to x_scopes enum - grok-tools.json: add voice, swarm to category enum Other: - .github/workflows/validate.yml: expand path trigger to specs/**; add schema-validate steps for grok-swarm and grok-voice; extend yaml-syntax check to cover specs/*.yaml - README.md: v1.2.0 → v2.0.0 badge/footer; add Grok 4.20 specs table; expand VS Code snippet; add schemas/index.json reference - CHANGELOG.md: add [2.0.0] section https://claude.ai/code/session_01MoaUSacqewHYzbYzMtTgQ6
1 parent 70d87ca commit 29b63b5

15 files changed

Lines changed: 1007 additions & 17 deletions

‎.github/workflows/validate.yml‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ on:
66
paths:
77
- ".grok/**"
88
- "schemas/**"
9+
- "specs/**"
910
pull_request:
1011
paths:
1112
- ".grok/**"
1213
- "schemas/**"
14+
- "specs/**"
1315

1416
jobs:
1517
# ── Job 1: YAML syntax ────────────────────────────────────────────────────
@@ -19,12 +21,12 @@ jobs:
1921
steps:
2022
- uses: actions/checkout@v4
2123

22-
- name: Parse all .grok/*.yaml files
24+
- name: Parse all .grok/*.yaml and specs/*.yaml files
2325
run: |
2426
python3 - <<'EOF'
2527
import yaml, glob, sys
2628
27-
files = sorted(glob.glob(".grok/*.yaml"))
29+
files = sorted(glob.glob(".grok/*.yaml") + glob.glob("specs/*.yaml"))
2830
errors = []
2931
for f in files:
3032
try:
@@ -37,7 +39,7 @@ jobs:
3739
print("\n".join(errors))
3840
sys.exit(1)
3941
40-
print(f"OK — all {len(files)} .grok/ files parse cleanly")
42+
print(f"OK — all {len(files)} YAML files parse cleanly")
4143
EOF
4244
4345
# ── Job 2: JSON schema files are valid JSON ────────────────────────────────
@@ -123,3 +125,9 @@ jobs:
123125

124126
- name: Validate grok-ui
125127
run: check-jsonschema --schemafile schemas/grok-ui.json .grok/grok-ui.yaml
128+
129+
- name: Validate grok-swarm spec
130+
run: check-jsonschema --schemafile schemas/grok-swarm.schema.json specs/grok-swarm.yaml
131+
132+
- name: Validate grok-voice spec
133+
run: check-jsonschema --schemafile schemas/grok-voice.schema.json specs/grok-voice.yaml

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,32 @@ Versions follow [Semantic Versioning](https://semver.org/).
55

66
---
77

8+
## [2.0.0] — 2026-04-18
9+
10+
Grok 4.20 support. Two new official YAML specs, a schema discovery manifest, and non-breaking additions to four existing schemas.
11+
12+
### Added
13+
- **`specs/grok-swarm.yaml`** — Annotated reference spec for Grok 4.20 multi-agent swarm orchestration. Configures swarm mode (`realtime-multi-agent`, `high-effort-16`, `single`), agent roles (coordinator, researcher, logic, creative, critic, moderator), model selection from the Grok 4.20 family, state persistence, and retry-with-backoff orchestration.
14+
- **`schemas/grok-swarm.schema.json`** — Full JSON Schema (draft/2020-12) for `grok-swarm.yaml`. Validates all swarm fields with constrained enums, ranges, and examples.
15+
- **`specs/grok-voice.yaml`** — Annotated reference spec for Grok 4.20 voice API. Configures STT/TTS models, voice identity, features (`real-time-conversation`, `emotion-aware`, `multi-speaker`, `speaker-diarization`), fallback behaviour, and safety limits.
16+
- **`schemas/grok-voice.schema.json`** — Full JSON Schema (draft/2020-12) for `grok-voice.yaml`.
17+
- **`schemas/index.json`** — Single-fetch discovery manifest listing all 14 schemas with `spec`, `spec_version`, `introduced_in`, `schema_url`, `file_glob`, and `required_by` fields. Use for VS Code integration and CI schema discovery.
18+
- **`docs/index.md`** — Overview of all 14 specs with anchor links, VS Code snippet, and CI integration notes.
19+
- **`docs/grok-swarm.md`** — Reference documentation for `grok-swarm.yaml`: mode table, agent role guide, tool set, state/orchestration field tables, examples, cross-references, and xAI SDK mapping.
20+
- **`docs/grok-voice.md`** — Reference documentation for `grok-voice.yaml`: model table, feature guide, field table, fallback table, voice + agent pattern example, cross-references, and xAI SDK mapping.
21+
22+
### Changed (non-breaking — additive enum extensions)
23+
- **`schemas/grok-agent.json`** `model_override` enum: added `grok-4.20`, `grok-4.20-multi-agent`, `grok-4.20-fast`
24+
- **`schemas/grok-config.json`** `default_model` and `fallback_model` enums: added same three Grok 4.20 variants
25+
- **`schemas/grok-security.json`** `x_scopes` enum: added `voice.read`, `voice.write` for Grok 4.20 voice API OAuth
26+
- **`schemas/grok-tools.json`** `category` enum: added `voice`, `swarm` for Grok 4.20 tool categories
27+
- **`README.md`**: updated badge and footer to v2.0.0; added Grok 4.20 specs table; expanded VS Code snippet with two new schema mappings; added `schemas/index.json` reference; updated "What's New" section
28+
29+
### No Breaking Changes
30+
All v1.x `.grok/` folders remain valid. Existing `model_override`, `default_model`, `fallback_model`, `x_scopes`, and `category` values are unchanged. Update `compatibility` to `grok-yaml-standards@2.0+` to opt in to swarm and voice specs.
31+
32+
---
33+
834
## [1.2.0] — 2026-04-16
935

1036
Official launch on X. See [LAUNCH.md](LAUNCH.md) for the full announcement and @grok endorsement.

‎README.md‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<h1>grok-yaml-standards</h1>
33
<p>Modular YAML extensions for Grok-native agents</p>
44

5-
[![Spec: v1.2.0](https://img.shields.io/badge/spec-v1.2.0-blue.svg)](CHANGELOG.md)
5+
[![Spec: v2.0.0](https://img.shields.io/badge/spec-v2.0.0-blue.svg)](CHANGELOG.md)
66
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
77
[![Compatible: xAI SDK](https://img.shields.io/badge/compatible-xAI%20SDK-FF6B00.svg)](https://docs.x.ai)
88
[![Compatible: grok-install](https://img.shields.io/badge/compatible-grok--install%401.0%2B-00B300.svg)](https://github.com/agentmindcloud/grok-install)
@@ -63,6 +63,15 @@ The library also ships four spec extensions added in v1.2.0:
6363
[`grok-analytics.yaml`](grok-analytics/), and
6464
[`grok-ui.yaml`](grok-ui/).
6565

66+
**Grok 4.20 specs** added in v2.0.0 live in [`specs/`](specs/) with their schemas in [`schemas/`](schemas/):
67+
68+
| File | Purpose | Requires |
69+
|------|---------|---------|
70+
| [`specs/grok-swarm.yaml`](specs/grok-swarm.yaml) | Multi-agent swarm orchestration — parallel execution, coordinator/specialist roles | grok@4.20+ |
71+
| [`specs/grok-voice.yaml`](specs/grok-voice.yaml) | Speech-to-text and text-to-speech voice session configuration | grok@4.20+ |
72+
73+
See [`docs/index.md`](docs/index.md) for the full 14-spec reference.
74+
6675
---
6776

6877
## Tool Registry
@@ -117,9 +126,10 @@ Full per-spec mappings in each spec's `schema.md` under **Cross-References**.
117126

118127
## JSON Schema Validation
119128

120-
All 12 specs ship a JSON Schema (draft/2020-12) in [`/schemas/`](schemas/).
129+
All 14 specs ship a JSON Schema (draft/2020-12) in [`/schemas/`](schemas/).
130+
A single-fetch discovery manifest listing every schema URL lives at [`schemas/index.json`](schemas/index.json).
121131

122-
Add live VS Code validation:
132+
Add live VS Code / JetBrains YAML validation:
123133

124134
```json
125135
{
@@ -129,20 +139,22 @@ Add live VS Code validation:
129139
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-security.json": ".grok/grok-security.yaml",
130140
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-prompts.json": ".grok/grok-prompts.yaml",
131141
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-config.json": ".grok/grok-config.yaml",
132-
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-tools.json": ".grok/grok-tools.yaml"
142+
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-tools.json": ".grok/grok-tools.yaml",
143+
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-swarm.schema.json": "specs/grok-swarm.yaml",
144+
"https://raw.githubusercontent.com/agentmindcloud/grok-yaml-standards/main/schemas/grok-voice.schema.json": "specs/grok-voice.yaml"
133145
}
134146
}
135147
```
136148

137149
---
138150

139-
## What's New in v1.2.0
151+
## What's New in v2.0.0
140152

141153
See [**CHANGELOG.md**](CHANGELOG.md) for the full version history and [**LAUNCH.md**](LAUNCH.md) for the official launch notes and @grok endorsement.
142154

143-
Highlights: 4 new spec extensions (grok-tools, grok-deploy, grok-analytics, grok-ui),
144-
JSON Schema upgraded to draft/2020-12, advanced `.grok/*.advanced.yaml` templates,
145-
comprehensive `schema.md` field references with SDK mapping tables for all 12 specs.
155+
Highlights: 2 new Grok 4.20 specs (`grok-swarm`, `grok-voice`), non-breaking Grok 4.20 model additions to 4 existing schemas, `schemas/index.json` discovery manifest, and `docs/` reference pages for all new specs.
156+
157+
**v1.2.0 highlights:** 4 spec extensions (grok-tools, grok-deploy, grok-analytics, grok-ui), JSON Schema draft/2020-12, advanced `.grok/*.advanced.yaml` templates, comprehensive `schema.md` field references with SDK mapping tables for all 12 specs.
146158

147159
---
148160

@@ -154,4 +166,4 @@ comprehensive `schema.md` field references with SDK mapping tables for all 12 sp
154166

155167
---
156168

157-
**v1.2.0** · `grok-install.yaml@1.0+` · Apache 2.0 · [Launched on X April 16, 2026](https://x.com/JanSol0s/status/2044691252327993364)
169+
**v2.0.0** · `grok-install.yaml@1.0+` · Apache 2.0 · [Launched on X April 16, 2026](https://x.com/JanSol0s/status/2044691252327993364)

‎docs/grok-swarm.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# grok-swarm
2+
3+
**File:** `specs/grok-swarm.yaml`
4+
**Schema:** [`schemas/grok-swarm.schema.json`](../schemas/grok-swarm.schema.json)
5+
**Introduced:** grok-yaml-standards v2.0.0
6+
**Requires:** grok@4.20+
7+
8+
---
9+
10+
## Overview
11+
12+
`grok-swarm.yaml` defines a coordinated group of Grok 4.20 agents that share a task queue and execute in parallel. A coordinator agent distributes subtasks; specialist agents (researcher, logic, critic, etc.) process them concurrently up to `max_parallel_calls`.
13+
14+
Swarms are best used for:
15+
- Deep research pipelines that benefit from parallel web + X search
16+
- Tasks requiring cross-checking (logic agent verifies researcher output)
17+
- High-throughput classification where `grok-4.20-fast` reduces latency and cost
18+
19+
---
20+
21+
## Modes
22+
23+
| Mode | Max Agents | Use When |
24+
|------|-----------|----------|
25+
| `realtime-multi-agent` | 16 | Interactive tasks requiring low-latency streaming responses |
26+
| `high-effort-16` | 16 | Long-running research; ignores `agent_count`, always uses max agents |
27+
| `single` | 1 | Single-agent fallback; swarm orchestration disabled |
28+
29+
---
30+
31+
## Agent Roles
32+
33+
| Role | Typical Model | Responsibility |
34+
|------|--------------|----------------|
35+
| `coordinator` | `grok-4.20-multi-agent` | Receives top-level task; dispatches subtasks to other agents |
36+
| `researcher` | `grok-4.20` | Gathers information via `web_search` and `x_search` |
37+
| `logic` | `grok-4.20` | Structured reasoning, code execution, fact-checking |
38+
| `creative` | `grok-4.20` | Generates text, threads, or media drafts |
39+
| `critic` | `grok-4.20-fast` | Reviews outputs; scores quality 1-10; flags issues |
40+
| `moderator` | `grok-4.20-fast` | Applies safety and compliance checks |
41+
| `custom` | any | User-defined role; set `system_prompt` explicitly |
42+
43+
---
44+
45+
## Swarm Tool Set
46+
47+
The following tools are available to swarm agents. Assign only what each role needs:
48+
49+
| Tool | Purpose |
50+
|------|---------|
51+
| `web_search` | Search the open web for current information |
52+
| `x_search` | Search X (Twitter) posts and threads |
53+
| `code_execution` | Run sandboxed Python/JS for computation and data processing |
54+
| `image_generation` | Generate images via Grok image model |
55+
| `voice_synthesis` | Synthesize audio (requires `grok-voice-tts-natural`) |
56+
57+
---
58+
59+
## State
60+
61+
| Field | Values | Default | Notes |
62+
|-------|--------|---------|-------|
63+
| `encrypted` | `true / false` | `true` | Always `true` in production |
64+
| `persistence` | `session-only / long-term / none` | `session-only` | `long-term` writes to repo memory store |
65+
66+
---
67+
68+
## Orchestration
69+
70+
| Field | Range | Default | Notes |
71+
|-------|-------|---------|-------|
72+
| `timeout_seconds` | 1–3600 | 300 | Coordinator aborts all agents after this |
73+
| `max_parallel_calls` | 1–16 | 4 | Reduce to lower API cost at the expense of speed |
74+
| `retry_policy.max_attempts` | 1–10 | 3 | Per-agent call |
75+
| `retry_policy.backoff` | `none / linear / exponential` | `exponential` | Exponential recommended |
76+
| `retry_policy.delay_seconds` | 1–60 | 2 | Base delay for linear/exponential backoff |
77+
78+
---
79+
80+
## Minimal Example
81+
82+
```yaml
83+
version: "2.0.0"
84+
author: "@yourhandle"
85+
compatibility:
86+
- "grok@4.20+"
87+
- "grok-yaml-standards@2.0+"
88+
89+
swarm:
90+
mode: "realtime-multi-agent"
91+
agent_count: 2
92+
agents:
93+
- role: "coordinator"
94+
model: "grok-4.20-multi-agent"
95+
tools: ["web_search"]
96+
- role: "critic"
97+
model: "grok-4.20-fast"
98+
system_prompt: "Review coordinator output and score accuracy 1-10."
99+
state:
100+
encrypted: true
101+
persistence: "session-only"
102+
orchestration:
103+
timeout_seconds: 120
104+
max_parallel_calls: 2
105+
```
106+
107+
See [`specs/grok-swarm.yaml`](../specs/grok-swarm.yaml) for the full annotated reference.
108+
109+
---
110+
111+
## Cross-References
112+
113+
**Depends On:**
114+
- [`grok-prompts.yaml`](../grok-prompts/schema.md) — `prompt_ref` keys must match entries in `prompt_library`
115+
- [`grok-security.yaml`](../grok-security/schema.md) — swarm agents inherit the active `safety_profile`
116+
- [`grok-tools.yaml`](../grok-tools/schema.md) — `tools` values must be registered in the tool registry
117+
118+
**Used By:**
119+
- [`grok-workflow.yaml`](../grok-workflow/schema.md) — a workflow step can invoke a swarm via `action: "grok-swarm"`
120+
121+
**Grok 4.20 SDK Mapping:**
122+
123+
| YAML field | xAI SDK param |
124+
|-----------|--------------|
125+
| `mode` | `swarm_mode` |
126+
| `agents[].model` | `model` per agent request |
127+
| `orchestration.max_parallel_calls` | `max_concurrency` |
128+
| `state.persistence` | `memory_scope` |

0 commit comments

Comments
 (0)