Communitygithub.com

broomva/skills

Tekton — the shared architecture-intent substrate for co-designing systems with the agent. One typed graph across six tiers (system / journey / data / infra / decisions / qualities); views are queries, not separate diagrams. The canonical artifact is a diff-friendly YAML model both human and agent read and write; it renders to Mermaid (agent-legible, GitHub-native) and a self-contained tabbed HTML viewer (human-visual). Cross-tier traceability (`tekton query <from> <to>`) answers "which infra does this user-journey step touch?" as a path query. USE WHEN: designing or thinking deeply about architecture, a system, a data model, user journeys/flows, or a technical plan WITH the agent; when a Category-C HTML doc isn't enough because you need to see AND edit AND traverse the design across tiers; "let's design X", "architect this", "model the system", "draw the flow", "how does this fit together", "diagram this", "/tekton". NOT FOR: a one-off throwaway diagram (use Mermaid inline); prose-only ADRs (write the ADR...

What is skills?

skills is a Claude Code agent skill that tekton — the shared architecture-intent substrate for co-designing systems with the agent. One typed graph across six tiers (system / journey / data / infra / decisions / qualities); views are queries, not separate diagrams. The canonical artifact is a diff-friendly YAML model both human and agent read and write; it renders to Mermaid (agent-legible, GitHub-native) and a self-contained tabbed HTML viewer (human-visual). Cross-tier traceability (`tekton query <from> <to>`) answers "which infra does this user-journey step touch?" as a path query. USE WHEN: designing or thinking deeply about architecture, a system, a data model, user journeys/flows, or a technical plan WITH the agent; when a Category-C HTML doc isn't enough because you need to see AND edit AND traverse the design across tiers; "let's design X", "architect this", "model the system", "draw the flow", "how does this fit together", "diagram this", "/tekton". NOT FOR: a one-off throwaway diagram (use Mermaid inline); prose-only ADRs (write the ADR...

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/broomva/skills/tree/HEAD/skills/design/tekton
View original→Browse all skills

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

Tekton — co-design architecture over one shared model

What it is

A substrate for human↔agent architecture partnership. The design lives in one YAML model both of us edit; git is the round-trip. You see it (HTML viewer); I read and write the same model. We think over the same context.

The failure it fixes: a hand-authored HTML/SVG doc is a terminal render — you can't traverse, query, or edit it back, and its diagrams carry no meaning. Tekton moves the live model upstream of the render.

Engine

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

python3 scripts/tekton.py validate <model.arch.yaml>       # integrity check
python3 scripts/tekton.py lint     <model.arch.yaml>       # v0.2 — fitness functions; exit 1 on violation
python3 scripts/tekton.py stats    <model.arch.yaml>       # node/edge/status/rule counts
python3 scripts/tekton.py views                            # list the 6 views
python3 scripts/tekton.py mermaid  <model.arch.yaml> <view># raw mermaid (embed/agent)
python3 scripts/tekton.py render   <model.arch.yaml> [-o out.html]  # on-brand HTML viewer
python3 scripts/tekton.py query    <model.arch.yaml> <from> <to>    # cross-tier path

v0.2 ontology upgrades (from the architecture review)

  • Containment — parent: on any node + boundary type; viewer renders nested groups, double-click to collapse/expand (C4-style drill-down).
  • Lifecycle — status: on nodes (current|target|deprecated; target renders dashed = as-is/to-be in one model) and full Nygard ADR fields on decisions (context, consequences, status, supersedes).
  • Qualities — qualities: block; NFRs constrains elements; surfaced in detail panel
    • dedicated view.
  • Fitness functions — rules: block (forbid-dep, no-cycle, layer-order); tekton lint is CI-gateable (exit 1). The design loop's independent verifier.

How the agent uses it in a design session

  1. Locate/create the model: <project>/docs/design/<name>.arch.yaml (or examples/ for scratch).
  2. Mutate as we think — add/adjust nodes, edges, decisions directly in the YAML as the conversation surfaces components, flows, data, infra, and ADRs.
  3. validate + lint after each substantive edit (dangling refs, bad types, fitness rules).
  4. render, then — BEFORE presenting the viewer as correct — run the geometry audit: bash tests/visual-audit.sh <model.arch.yaml>. It headless-renders every view and FAILS on node overlaps or empty captures. Claiming "the diagram is correct" without it is the exact failure the first dogfood caught (disconnected in-group edges, doubled nodes — invisible to DOM-count probes, caught only by geometry). Deep-link a view with #<view> in the URL.
  5. query to answer traceability questions ("what does this touch?") instead of guessing.
  6. Steer → repeat. The human edits the YAML or the viewer intent; git diff is the handoff.

Known cosmetic residuals (not audit failures): journey loop-back edges make ELK break the cycle at an arbitrary step (a loop must break somewhere); adjacent parallel-edge labels can sit close in dense groups.

Conventions

  • Model files: *.arch.yaml. Rendered viewer: *.view.html (gitignore or commit — your call).
  • One model per bounded system; link systems with external nodes + uses edges.
  • Decisions (ADRs) are first-class nodes — pin them to what they govern.
  • Category-C HTML reports become a downstream export of a model, not the source of truth.

Rendering — why not Mermaid

The primary viewer is a custom renderer, not Mermaid. Mermaid's theming ceiling can't express the Broomva Design System (OKLCH blue-axis, matte cards, earned glass, comet-glow) and its dagre layout degrades on dense graphs. Instead: elkjs computes the layout in-browser (pure JS → the output stays a single self-contained HTML file), and nodes are drawn as Broomva matte cards (glass reserved for the floating detail panel, per the DS's "glass is earned" rule). Design tokens are inlined from the Broomva Design System. tekton mermaid stays ONLY as a throwaway embed/agent-legible target.

Roadmap (v0 → v2)

  • v0.2 (now): YAML model · validate + lint (fitness functions) · 6 views · on-brand elkjs viewer (containment collapse/expand, as-is/to-be, click-to-trace, glass detail panel) · cross-tier query · Mermaid fallback embed.
  • v1: two-way round-trip (drag/edit in the viewer → serialize back to YAML); MCP server (validated mutations so the agent can't emit an invalid model); vendor the full Broomva Design System for a React-Flow interactive canvas.
  • v2: CRDT (loro) real-time human↔agent co-editing; live sync into Prosopon as a surface.

Status

v0 dogfood — internal design tool. Skillify (tested + registered) once the design loop has been used on ≥3 real systems (rule-of-three).

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'.

Related 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