Communitygithub.com

Tekton — Co-Design-Architektur über ein gemeinsames Modell

Ein Substrat, das die gemeinsame Entwicklung von Architekturentwürfen zwischen Mensch und KI-Agent ermöglicht, basierend auf einem einzigen, versionierbaren YAML-Modell.

Was ist Tekton — Co-Design-Architektur über ein gemeinsames Modell?

Tekton ist ein Werkzeug für die partnerschaftliche Architekturgestaltung zwischen Mensch und KI-Agent. Es löst das Problem, dass handgeschriebene HTML/SVG-Diagramme eine Sackgasse darstellen: Sie können weder traversiert, abgefragt noch zurückbearbeitet werden. Tekton stellt das Live-Modell stromaufwärts der Render-Ausgabe. Das Modell lebt in einer einzigen YAML-Datei, die sowohl der Mensch als auch der Agent lesen und schreiben können; Git dient als Roundtrip. Der Agent kann das YAML-Modell während eines Design-Gesprächs direkt mutieren, es mit `tekton validate` und `tekton lint` auf Korrektheit prüfen lassen und mit `tekton render` einen ansprechenden, barrierefreien HTML-Viewer erzeugen, der als Single-Page-App mit interaktiven Diagrammen (ELKJS-Layout, ergonomische Bedienung, Zoom, Filter, Click-to-Trace) arbeitet. Der Viewer ist kein Terminal-Render, sondern ein interaktives Werkzeug – der Mensch kann darin editieren und die Änderungen zurück ins YAML serialisieren (v1). Tekton unterstützt sechs Sichten (System, Journey, Daten, Infrastruktur, Entscheidungen, Qualitäten) und Cross-Tier-Abfragen (z.B. „Welche Infrastruktur berührt dieser User-Journey-Schritt?“). Es ist für tiefgreifende Architekturarbeit gedacht, nicht für einmalige Wegwerf-Diagramme. Die Ontologie umfasst Containment (geschachtelte Gruppen), Lebenszyklus (Status: current, target, deprecated), Qualitäten (NFRs) und Fitnessfunktionen (CI-gateable Regeln wie `no-cycle`, `forbid-dep`). Tekton wird derzeit als internes Dogfood-Werkzeug entwickelt und soll nach erfolgreichem Einsatz auf mindestens drei echten Systemen als Skill registriert werden.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/broomva/skills/tree/HEAD/skills/design/tekton
Original anzeigen→Alle Skills durchsuchen

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Dokumentation

Tekton — Architektur gemeinsam über ein einheitliches Modell entwickeln

Was es ist

Ein Substrat für die Architekturpartnerschaft zwischen Mensch und KI-Agent. Der Entwurf lebt in einem YAML-Modell, das wir beide bearbeiten; Git ist der Roundtrip. Du siehst es (HTML-Viewer); ich lese und schreibe das gleiche Modell. Wir denken im selben Kontext.

Der Fehler, den es behebt: Ein handgeschriebenes HTML/SVG-Dokument ist ein terminales Rendering – du kannst es nicht traversieren, abfragen oder zurückbearbeiten, und seine Diagramme tragen keine Bedeutung. Tekton verschiebt das Live-Modell stromaufwärts des Renderings.

Engine

scripts/tekton.py (Python 3, pyyaml). Ontologie in references/ontology.md.

python3 scripts/tekton.py validate <model.arch.yaml>       # Integritätsprüfung
python3 scripts/tekton.py lint     <model.arch.yaml>       # v0.2 — Fitnessfunktionen; Exit 1 bei Verstoß
python3 scripts/tekton.py stats    <model.arch.yaml>       # Knoten/Kanten/Status/Regel-Zählungen
python3 scripts/tekton.py views                            # Liste der 6 Sichten
python3 scripts/tekton.py mermaid  <model.arch.yaml> <view># Roh-Mermaid (Einbettung/Agent)
python3 scripts/tekton.py render   <model.arch.yaml> [-o out.html]  # Markenkonformer HTML-Viewer
python3 scripts/tekton.py query    <model.arch.yaml> <from> <to>    # Sichtübergreifender Pfad

v0.2 Ontologie-Upgrades (aus der Architekturüberprüfung)

  • Enthaltenseinsbeziehung — parent: bei jedem Knoten + Typ boundary; Viewer rendert verschachtelte Gruppen, Doppelklick zum Einklappen/Ausklappen (C4-ähnlicher Drill-Down).
  • Lebenszyklus — status: an Knoten (current|target|deprecated; target wird gestrichelt dargestellt = Ist/Soll in einem Modell) und vollständige Nygard-ADR-Felder an Entscheidungen (context, consequences, status, supersedes).
  • Qualitäten — qualities:-Block; NFRs constrains-Elemente; dargestellt im Detail-Panel + eigener Sicht.
  • Fitnessfunktionen — rules:-Block (forbid-dep, no-cycle, layer-order); tekton lint ist CI-gateable (Exit 1). Der unabhängige Verifizierer der Designschleife.

Wie der Agent es in einer Design-Sitzung nutzt

  1. Modell finden/erstellen: <project>/docs/design/<name>.arch.yaml (oder examples/ für Spielwiese).
  2. Mutieren während des Denkens — Knoten, Kanten, Entscheidungen direkt im YAML hinzufügen/anpassen, während das Gespräch Komponenten, Flows, Daten, Infrastruktur und ADRs zutage fördert.
  3. validate + lint nach jeder substanziellen Änderung (verwaiste Referenzen, falsche Typen, Fitnessregeln).
  4. render, dann – BEVOR der Viewer als korrekt präsentiert wird – die Geometrie-Prüfung ausführen: bash tests/visual-audit.sh <model.arch.yaml>. Es rendert jede Sicht headless und SCHLÄGT FEHL bei Knotenüberlappungen oder leeren Aufnahmen. Zu behaupten, „das Diagramm ist korrekt“, ohne diesen Test, ist genau der Fehler, den das erste Dogfood aufgedeckt hat (nicht verbundene In-Group-Kanten, doppelte Knoten – unsichtbar für DOM-Zählung, erkannt nur durch Geometrie). Deep-Link zu einer Sicht mit #<view> in der URL.
  5. query, um Traceability-Fragen zu beantworten („Was berührt das?“), anstatt zu raten.
  6. Steuern → wiederholen. Der Mensch bearbeitet das YAML oder die Viewer-Intention; der Git-Diff ist die Übergabe.

Bekannte kosmetische Reste (keine Prüfungsfehler): Journey-Rückkopplungskanten zwingen ELK, den Zyklus an einem beliebigen Schritt zu brechen (eine Schleife muss irgendwo brechen); benachbarte parallele Kantenbeschriftungen können in dichten Gruppen nah beieinander liegen.

Konventionen

  • Modell-Dateien: *.arch.yaml. Gerenderter Viewer: *.view.html (gitignore oder committen – deine Entscheidung).
  • Ein Modell pro abgegrenztem System; Systeme mit external-Knoten + uses-Kanten verknüpfen.
  • Entscheidungen (ADRs) sind erstklassige Knoten – verknüpfe sie mit dem, was sie govern.
  • Category-C HTML-Berichte werden zu einem Downstream-Export eines Modells, nicht zur Quelle der Wahrheit.

Rendering – warum nicht Mermaid

Der primäre Viewer ist ein benutzerdefinierter Renderer, nicht Mermaid. Mermaid theming ceiling kann das Broomva Design System nicht ausdrücken (OKLCH-Blauachse, matte Karten, earned glass, comet-glow) und sein dagre-Layout degradiert auf dichten Graphen. Stattdessen: elkjs berechnet das Layout im Browser (reines JS → die Ausgabe bleibt eine einzige, in sich geschlossene HTML-Datei), und Knoten werden als Broomva-Mattkarten gezeichnet (Glas bleibt dem schwebenden Detail-Panel vorbehalten, gemäß der „Glas wird verdient“-Regel des DS). Design-Tokens sind aus dem Broomva Design System inline eingefügt. tekton mermaid bleibt NUR als Einweg-Einbettungs-/Agent-lesbares Ziel bestehen.

Roadmap (v0 → v2)

  • v0.2 (jetzt): YAML-Modell · validate + lint (Fitnessfunktionen) · 6 Sichten · on-brand elkjs-Viewer (Containment einklappen/ausklappen, Ist/Soll, Klick-zu-Trace, Glas-Detail-Panel) · sichtübergreifende Abfrage · Mermaid-Fallback-Einbettung.
  • v1: bidirektionaler Roundtrip (ziehen/bearbeiten im Viewer → zurück ins YAML serialisieren); MCP-Server (validierte Mutationen, damit der Agent kein ungültiges Modell ausgeben kann); das vollständige Broomva Design System für eine React-Flow interaktive Leinwand als Anbieter.
  • v2: CRDT (loro) Echtzeit-Mensch↔Agent-Co-Editing; Live-Synchronisation in Prosopon als Oberfläche.

Status

v0 Dogfood – internes Design-Werkzeug. Skillify (getestet + registriert), sobald die Design-Schleife auf ≥3 realen Systemen eingesetzt wurde (Drei-Regel).

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

broomva/skills

Local TTS, voice cloning, voice design, and video dubbing via the OmniVoice Studio MCP server (open-source ElevenLabs alternative; nothing leaves the machine, runs on MPS/CUDA/CPU). Use when: (1) generating speech from text in any of 646 languages, (2) cloning a voice from a 3-second reference clip, (3) designing a voice by gender/age/accent/pitch/style, (4) dubbing a video into another language, (5) listing voice profiles or personality presets, (6) producing narration where privacy, cost, or absent API keys matter, (7) non-English narration where Edge TTS/kokoro fall short, (8) batch audio for blog posts or content pipelines. Triggers: 'omnivoice', 'voice clone', 'clone this voice', 'tts', 'narrate', 'generate speech', 'voice synthesis', 'dub video', 'voice design', 'local tts', 'multilingual voice', 'narrate this post', 'elevenlabs alternative'.

broomva/skills

>- Speak an explanation out loud while working in any project — tiered text-to-speech with a pluggable backend (ElevenLabs by default and quota-guarded, macOS `say` via `--fast` for free instant local speech, local OmniVoice as an unlimited private tier). Markdown-aware, so code fences, URLs and deep paths collapse to short spoken placeholders instead of being dictated character by character, while snake_case identifiers survive intact so the listener can still search for them. Every utterance is saved to disk for later replay. Also carries a **talk mode** toggle: turn it on and the agent speaks a full readback of every turn, for as long as that session lasts — the whole response, not a summary of it, with `brief` and `marker` levels for when you want less. Talk mode is off by default and scoped to the single session that enabled it, so parallel agents in other worktrees stay silent. Use when the user asks to hear something rather than read it — an explanation of a change, a walkthrough of what just happen...

broomva/skills

Shop Tiendas D1 (Colombia, d1.com.co) from the command line — search the catalogue, resolve your nearest physical store, price a basket against that store's real stock, and quote delivery. D1 runs VTEX IO (account `d1tiendas`), so this drives its public storefront API with no admin key at all — catalogue and cart work fully anonymously, and a one-time emailed code unlocks order history. Handles the two traps that make naive D1 automation wrong — availability is regionalized (an unregioned query reports a national catalogue nobody can actually buy from) and prices arrive in two different units (search reports whole pesos, checkout reports hundredths, a silent 100x). Builds and prices baskets; it deliberately cannot pay, handing a checkout URL to a human instead. USE WHEN the user wants to find D1 products or prices, check whether D1 delivers somewhere, build or cost a D1 grocery basket, compare D1 items, or review their D1 orders. NOT FOR other Colombian retailers (Éxito, Jumbo, Ara, Alkosto), and not for c...

broomva/skills

Stateful, local-first household toxics inventory + swap engine. Identify the items in a home that carry endocrine disruptors and persistent chemicals (BPA/BPS, phthalates, PFAS/PTFE, parabens, flame retardants, VOCs, microplastics), score each by *real* exposure (severity x presence x how it's used x condition), and track the swap to a safer alternative from "flagged" -> "sourced" -> "swapped". Ships a grounded, cited knowledge graph of ~20 hazards, ~40 item-classes, and ~40 alternatives. Hands sourcing off to the `procurer` skill. The skill's state is the source of truth — the agent is the app.

broomva/skills

Generate a polished Remotion video and X thread showcasing the full agent skills inventory. Use when creating social media content about skills, rendering category-based skill visualizations, or producing animated showcases of agent capabilities. Triggers on "skills video", "showcase skills", "skills thread", "render skills", "social content for skills", or requests to visualize the skills inventory.

broomva/skills

OpenCaptions extension for Content Engine — adds intent-driven CWI (Caption With Intent) captions to the post-production pipeline. Hooks into the grade → caption → final stage. Generates captions that understand video intent (pitch, volume, emotion, emphasis) and style themselves accordingly with variable font weight, size, and color. Uses the OpenCaptions CLI or MCP server. Triggers on: 'add captions', 'opencaptions', 'CWI captions', 'intent captions'.

broomva/skills

Produce polished product launch videos using the Liquid Glass aesthetic — dark void backgrounds, 3D perspective floating UI panels, particle effects, spring animations, and cinematic pacing. Built on Remotion with Imagen 4.0 for frames and Veo 3.1 for B-roll. Use when: (1) creating a product demo or launch video, (2) showcasing a UI/app/tool with cinematic polish, (3) building a social-ready video from screenshots and renders, (4) applying the liquid glass floating panel style, (5) composing Remotion videos with 3D transforms and spring animations. Triggers on: 'launch video', 'product video', 'liquid glass video', 'demo video', 'showcase video', 'remotion video', 'floating panel', 'glass aesthetic'.

Verwandte Skills

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community