Leitfaden für Entwickler

Wie Leitvia aufgebaut ist, wie der Design-Vertrag funktioniert und wie dein Code, deine Agenten und deine eigenen Blöcke daran andocken. Für Entwickler und Agenturen, die Websites mit Leitvia bauen oder Leitvia erweitern.

Leitvia hält sich an die Standards, die WordPress für KI-Agenten setzt, und wird das weiter tun: die offiziellen Skills in WordPress/agent-skills, die Abilities API von WordPress und den MCP Adapter. Alles hier funktioniert mit den Werkzeugen von WordPress selbst. Leitvia legt Prüfungen und einen Design-Vertrag darüber.

Die Pakete

Leitvia besteht aus kleinen Paketen. Jedes hat eine klare Aufgabe, und keines greift in den Code eines anderen.

• Theme Leitvia: Block-Theme mit Design-Tokens, Templates, Stilvarianten und Patterns, ohne JavaScript und ohne Einstellungsseite. Kostenlos, auf GitHub.
• Leitvia Studio: Plugin mit Pattern Lab, Token-Sets, Inhaltsmodell, Blöcken und dem Agent-Gateway mit 59 Abilities. Kostenlos, auf GitHub.
• Leitvia Child: Child Theme als Vorlage für Patterns und Templates, die du als Dateien pflegst. Kostenlos, auf GitHub.
• Leitvia Block Starter: Plugin als Vorlage mit einem Beispielblock, für deine eigenen Blöcke. Kostenlos, auf GitHub.
• Leitvia Skills: Agent-Skills, Workflows und das Agenten-Handbuch für Claude Code, Codex, Cursor und andere Agenten. Kostenlos, auf GitHub.
• Leitvia Pro: Add-on mit Pro-Blöcken, Branchen-Kits, Live-Daten, Flotten-Abgleich und White Label. Kostenpflichtig, aus deinem Konto.

Pro-Funktionen stecken nur in Leitvia Pro. Theme und Studio bieten Erweiterungspunkte, also Registries für Blöcke, Patterns, Abilities, Rezepte und mehr (siehe docs/extension-api.md in Studio). Pro und deine eigenen Plugins nutzen sie auf dieselbe Weise.

Der Design-Vertrag

Das Theme beschreibt sein Design in leitvia-contract.json: Farbrollen wie surface, ink und accent, Abstände von xxs bis xxxl, Schriftgrößen von meta bis display, die erlaubten Kontrastpaare, Block-Stile, Seitenrahmen und die Komposition jedes Patterns. design.md erklärt dasselbe in Textform. Studio, das Lab und die Agenten lesen den Vertrag. Ein Pattern, das ihm folgt, passt deshalb zu jeder Stilvariante und jedem Token-Set.

Im Markup stehen Rollen, nie feste Werte:

<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|xl","bottom":"var:preset|spacing|xl"}}},"backgroundColor":"surface-alt","textColor":"ink"} -->

Die Standard-Themes von WordPress nutzen andere Slugs, und Agenten, die mit ihnen trainiert wurden, schreiben base, contrast oder den Abstand 50. Leitvia bildet diese Core-Slugs unter coreAliases im Vertrag auf seine Rollen ab. Das Theme definiert jeden Alias als CSS-Variable und Klasse, Studio schreibt ihn beim Speichern auf die Rolle um, und sein Token-Lint lehnt jeden anderen Slug ab, den das Theme nicht kennt.

Die Aliase sind ein Sicherheitsnetz, kein zweites Vokabular. Hex-Farben, px-Werte und !important lehnen der Token-Lint von Studio und die Prüfungen des Themes ab.

Abilities über REST und MCP

Leitvia Studio meldet 59 Abilities bei der Abilities API von WordPress an: 49 auf jeder Website und 10 weitere mit WooCommerce. 25 davon lesen nur. Jeder Schreibvorgang läuft durch dieselbe Pipeline, egal auf welchem Weg er kommt: Prüfung von Schema und Rechten, Kontrast- und Token-Prüfung, ein Snapshot zum Zurücksetzen und die Autonomiestufe, die du für den Bereich festlegst. Ein Agent meldet sich als eigener WordPress-Benutzer mit einem Anwendungspasswort an. Du legst ihn unter Leitvia Studio, Agents an.

Es gibt drei Wege hinein, alle mit denselben Prüfungen:

• Die REST-Routen der Abilities API unter /wp-json/wp-abilities/v1. Dafür brauchst du kein weiteres Plugin.
• Der MCP-Server leitvia unter /wp-json/leitvia-studio/v1/mcp, ein Tool je Ability, mit Code, Meldung und Daten jeder Ablehnung. Er braucht das Plugin MCP Adapter 0.7.
• Der Standard-Server des MCP Adapters unter /wp-json/mcp/mcp-adapter-default-server. Seine Tools discover-abilities, get-ability-info und execute-ability finden und starten die Abilities von Leitvia ebenfalls.

Die Abfrage aller Abilities liefert jede mit ihrem Schema für Eingabe und Ausgabe und ihren Annotationen (readonly, destructive, idempotent):

curl -u "agent-login:application password" \
  "https://example.org/wp-json/wp-abilities/v1/abilities?category=leitvia&per_page=100"

[
  {
    "name": "leitvia/get-contract",
    "label": "Get contract",
    "input_schema": { ... },
    "output_schema": { ... },
    "meta": {
      "annotations": { "readonly": true, "destructive": false, "idempotent": true, "openWorldHint": false }
    }
  },
  ...
]

Abilities, die nur lesen, laufen mit GET, die Eingabe steht in den Query-Argumenten:

curl -u "agent-login:application password" \
  "https://example.org/wp-json/wp-abilities/v1/abilities/leitvia/get-seo/run?input[posts][]=22"

{
  "items": [
    {
      "post": 22,
      "title": "About",
      "hash": "a119346faf5294bb",
      "seo": { "title": "", "description": "", "noindex": false, ... }
    }
  ],
  "indexable": true,
  ...
}

Schreibende Abilities laufen mit POST und einem JSON-Body. Ein Schreibvorgang nennt den Hash dessen, was er ändert (base_hash, leer für etwas Neues). Die Antwort sagt, ob die Änderung live ging oder in einem Änderungspaket wartet:

curl -u "agent-login:application password" -X POST \
  -H "Content-Type: application/json" \
  "https://example.org/wp-json/wp-abilities/v1/abilities/leitvia/create-content/run" \
  -d '{"input": {"post_type": "page", "title": "Opening hours", "base_hash": "",
       "content": "<!-- wp:paragraph -->\n<p>We are open from Monday to Friday.</p>\n<!-- /wp:paragraph -->",
       "package": "opening-hours"}}'

{ "mode": "package", "level": "draft", "target": { "post": 0 }, "package": 32548, "findings": [] }

"mode": "package" heißt: Die Änderung ist noch nicht passiert. Sie wartet in der Inbox von Leitvia Studio, bis eine Person sie übernimmt oder ablehnt. Dein Code meldet das Paket und versucht keinen anderen Weg. Zwei Antworten brauchen eine Behandlung:

• 409 leitvia_stale_hash: Das Ziel hat sich seit dem Lesen geändert. Lies es neu oder nimm data.current_hash aus der Antwort und wiederhole den Aufruf einmal.
• 429 leitvia_rate_limited: Warte so viele Sekunden, wie der Header Retry-After nennt, und schick denselben Aufruf noch einmal.

HTTP/1.1 409 Conflict

{
  "code": "leitvia_stale_hash",
  "message": "The target changed since it was read. Read it again and repeat the change on the current state with base_hash a119346faf5294bb.",
  "data": {
    "status": 409,
    "reason": "stale_hash",
    "target": { "post": 22 },
    "next_ability": "leitvia/get-page-outline",
    "retry": "once",
    "current_hash": "a119346faf5294bb"
  }
}

Jede Ability hat eine Seite im Agenten-Handbuch von Leitvia Skills mit Eingabe, Ausgabe, Methode und Ablehnungen. Die Seite handbook/core-rest.md fasst den Weg über REST zusammen.

Agent-Skills

Agenten lesen Skills, um zu wissen, wie sie arbeiten. Die offiziellen Skills von WordPress bringen ihnen WordPress selbst bei: wp-block-development, wp-block-themes, wp-patterns, wp-abilities-api, wp-plugin-development und weitere. Leitvia Skills ergänzt elf Skills für Leitvia-Websites (Einrichtung, Design, Seiten, Patterns, Wartung, Barrierefreiheit, Migration, Shop, News, Suche und Berichte) und drei Workflows. Sie haben denselben Aufbau wie die Skills von WordPress: When to use, Inputs required, Procedure, Verification, Failure modes und Escalation.

Beide Skill-Sammlungen arbeiten nebeneinander. Auf einer Leitvia-Website haben die Abilities von Leitvia Vorrang, und ein Agent schreibt nie Dateien in das Theme leitvia. Für Claude Code:

claude plugin install leitvia-skills --marketplace cmsadmins/leitvia-skills
npx skills add WordPress/agent-skills --skill wp-block-development wp-abilities-api

Andere Agenten bekommen die Ordner skills, handbook und workflows aus dem Release-Zip oder einem Klon des Repositorys. Das README von Leitvia Skills nennt den Ordner, den der jeweilige Agent liest.

Das Child Theme

Manche Arbeit liegt in Dateien: ein Pattern unter Versionskontrolle, ein Template, das ein Agent mit einem WordPress-Skill schreibt, ein Template-Teil einer Agentur. Im Theme Leitvia wären diese Dateien mit dem nächsten Update weg. Sie gehören deshalb in Leitvia Child. Es erbt alles von Leitvia und bringt kein eigenes CSS und keine eigenen Presets mit.

Ein Pattern im Child Theme folgt den Regeln des Themes: nur Rollen, ein Kopf mit Title, Slug, Categories und Description und ein Eintrag im Vertrag des Child Themes. Dieser Vertrag ergänzt nur Patterns, Rollen und Paare kommen von Leitvia:

{
  "extends": "leitvia",
  "patterns": [
    {
      "slug": "leitvia-child/content-starter",
      "title": "Starter section",
      "area": "content",
      "composition": { "tone": "surface", "density": "regular", "layout": "centered", "weight": "light", "role": "context", "width": "reading" }
    }
  ]
}

WordPress speichert globale Stile und bearbeitete Templates je Theme. Ist Leitvia Studio aktiv, kopiert ein Wechsel von Leitvia zu Leitvia Child sie mit, das aktive Token-Set eingeschlossen, solange das Child Theme noch keine eigenen hat. Die Originale bleiben, ein Wechsel zurück findet sie also unverändert. Unsere eigenen Kundenwebsites kommen ohne Child Theme aus: Was sie brauchen, kommt ins Theme, in Studio oder in Pro, damit jede Website es bekommt.

Dein eigener Block

Ein Block gehört in ein Plugin. Wechselt eine Website das Theme, bleibt der Block in ihren Inhalten stehen. Hat ein Theme oder Child Theme ihn registriert, zeigt danach jeder Beitrag, der ihn nutzt, einen nicht unterstützten Block. Leitvia Block Starter ist ein kleines Plugin mit einem dynamischen Beispielblock, leitvia-block-starter/callout. Es läuft mit jedem Block-Theme, mit Leitvia kommen Farben, Abstände und Größen aus den Rollen.

1. Kopier den Plugin-Ordner, benenne ihn um und ersetze in allen Dateien den Slug leitvia-block-starter, das Präfix leitvia_block_starter und den Paketnamen.
2. Benenne den Blockordner unter src/blocks/ um und setze name in block.json. Der Name ist eine feste Schnittstelle: Sobald Inhalte den Block nutzen, ändert er sich nie mehr.
3. Führ npm install und npm run build aus. Der Build schreibt build/blocks-manifest.php, und das Plugin registriert jeden Block darin mit wp_register_block_types_from_metadata_collection(). Ein neuer Block ist ein neuer Ordner, am PHP änderst du nichts.
4. Halte die Attribute knapp und typisiert. Farben, Abstände, Typografie und Rahmen kommen über supports, so bietet der Editor die Presets des Themes an.
5. Gib das Markup in render.php mit get_block_wrapper_attributes() aus und escape spät. Ein dynamischer Block darf sein Markup mit jedem Release ändern, ohne dass gespeicherte Inhalte ungültige Blöcke zeigen.
6. Teste mit PHPUnit, PHPCS, PHPStan und Plugin Check. Füg den Block danach im Editor ein, speichere und lade neu.

Die block.json des Beispiels holt alles Sichtbare aus dem Theme:

{
  "apiVersion": 3,
  "name": "leitvia-block-starter/callout",
  "attributes": {
    "heading": { "type": "string", "default": "" },
    "level": { "type": "integer", "enum": [ 2, 3, 4, 5, 6 ], "default": 2 },
    "text": { "type": "string", "default": "" }
  },
  "supports": {
    "html": false,
    "color": { "background": true, "text": true, "link": true },
    "spacing": { "margin": true, "padding": true },
    "typography": { "fontSize": true, "lineHeight": true },
    "__experimentalBorder": { "color": true, "radius": true, "style": true, "width": true }
  },
  "render": "file:./render.php"
}

Sein Stylesheet setzt nur Vorgaben, in :where(), damit Einstellungen im Editor immer gewinnen, mit der Rolle von Leitvia zuerst und dem Core-Slug als Rückfall für andere Themes:

:where(.wp-block-leitvia-block-starter-callout) {
  padding: var(--wp--preset--spacing--m, var(--wp--preset--spacing--40, 1.5rem));
  border: thin solid var(--wp--preset--color--stroke, currentColor);
  background-color: var(--wp--preset--color--surface-alt, var(--wp--preset--color--tertiary, transparent));
  color: var(--wp--preset--color--ink, var(--wp--preset--color--contrast, inherit));
}

Agenten, die an einem Block-Plugin arbeiten, folgen dem WordPress-Skill wp-block-development, für Verhalten im Frontend zusätzlich wp-interactivity-api. Das README des Starters ergänzt die Regeln von Leitvia in elf Schritten, vom Umbenennen bis zum Release-Zip.

Prüfungen vor dem Release

• Jede REST-Route von Studio beschreibt ihre Antwort: OPTIONS auf eine Route liefert ihr Schema, und schreibende Routen prüfen ihre Argumente, bevor der Callback läuft.
• Jede Ability hat vollständige Annotationen und eine Beschreibung für jedes Pflichtfeld, wie es der WordPress-Skill wp-abilities-verify erwartet.
• Markup besteht den Token-Lint: nur Rollen, kein Hex, kein px, kein unbekanntes Preset. Das Pattern Lab zeigt das Ergebnis jedes Patterns.
• Plugin-Code besteht PHPCS mit den WordPress Coding Standards, PHPStan Level 8 und Plugin Check, Theme-Code besteht Theme Check.
• Seiten bestehen axe für WCAG 2.2 AA und die Prüfschritte der BITV 2.0, die ein Test prüfen kann. Was nur ein Mensch prüfen kann, bleibt auf der Liste deiner Abnahme.

Quellcode und Releases

• Theme Leitvia mit design.md und leitvia-contract.json
• Leitvia Studio mit docs/extension-api.md
• Leitvia Child
• Leitvia Block Starter
• Leitvia Skills mit dem Agenten-Handbuch
• WordPress/agent-skills, die offiziellen Skills von WordPress
• Changelog aller Pakete