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
- 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
- Locate/create the model:
<project>/docs/design/<name>.arch.yaml (or examples/ for scratch).
- Mutate as we think — add/adjust nodes, edges, decisions directly in the YAML as the
conversation surfaces components, flows, data, infra, and ADRs.
validate + lint after each substantive edit (dangling refs, bad types, fitness rules).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.query to answer traceability questions ("what does this touch?") instead of guessing.- 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).
1---2name: tekton3description: 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); 4license: MIT5---67# Tekton — co-design architecture over one shared model89## What it is10A substrate for **human↔agent architecture partnership**. The design lives in one11YAML model both of us edit; git is the round-trip. You *see* it (HTML viewer); I *read12and write* the same model. We think over the same context.1314The failure it fixes: a hand-authored HTML/SVG doc is a terminal render — you can't15traverse, query, or edit it back, and its diagrams carry no meaning. Tekton moves the16live model **upstream** of the render.1718## Engine19`scripts/tekton.py` (Python 3, pyyaml). Ontology in `references/ontology.md`.2021```bash22python3 scripts/tekton.py validate <model.arch.yaml> # integrity check23python3 scripts/tekton.py lint <model.arch.yaml> # v0.2 — fitness functions; exit 1 on violation24python3 scripts/tekton.py stats <model.arch.yaml> # node/edge/status/rule counts25python3 scripts/tekton.py views # list the 6 views26python3 scripts/tekton.py mermaid <model.arch.yaml> <view># raw mermaid (embed/agent)27python3 scripts/tekton.py render <model.arch.yaml> [-o out.html] # on-brand HTML viewer28python3 scripts/tekton.py query <model.arch.yaml> <from> <to> # cross-tier path29```3031## v0.2 ontology upgrades (from the architecture review)32- **Containment** — `parent:` on any node + `boundary` type; viewer renders nested groups,33 double-click to collapse/expand (C4-style drill-down).34- **Lifecycle** — `status:` on nodes (`current|target|deprecated`; target renders dashed =35 as-is/to-be in one model) and full Nygard ADR fields on decisions (`context`,36 `consequences`, `status`, `supersedes`).37- **Qualities** — `qualities:` block; NFRs `constrains` elements; surfaced in detail panel38 + dedicated view.39- **Fitness functions** — `rules:` block (`forbid-dep`, `no-cycle`, `layer-order`);40 `tekton lint` is CI-gateable (exit 1). The design loop's independent verifier.4142## How the agent uses it in a design session431. **Locate/create** the model: `<project>/docs/design/<name>.arch.yaml` (or `examples/` for scratch).442. **Mutate as we think** — add/adjust nodes, edges, decisions directly in the YAML as the45 conversation surfaces components, flows, data, infra, and ADRs.463. **`validate` + `lint`** after each substantive edit (dangling refs, bad types, fitness rules).474. **`render`**, then — BEFORE presenting the viewer as correct — run the geometry audit:48 `bash tests/visual-audit.sh <model.arch.yaml>`. It headless-renders every view and FAILS on49 node overlaps or empty captures. Claiming "the diagram is correct" without it is the exact50 failure the first dogfood caught (disconnected in-group edges, doubled nodes — invisible to51 DOM-count probes, caught only by geometry). Deep-link a view with `#<view>` in the URL.525. **`query`** to answer traceability questions ("what does this touch?") instead of guessing.536. **Steer → repeat.** The human edits the YAML or the viewer intent; git diff is the handoff.5455Known cosmetic residuals (not audit failures): journey loop-back edges make ELK break the56cycle at an arbitrary step (a loop must break somewhere); adjacent parallel-edge labels can57sit close in dense groups.5859## Conventions60- Model files: `*.arch.yaml`. Rendered viewer: `*.view.html` (gitignore or commit — your call).61- One model per bounded system; link systems with `external` nodes + `uses` edges.62- Decisions (ADRs) are first-class nodes — pin them to what they `govern`.63- Category-C HTML reports become a **downstream export** of a model, not the source of truth.6465## Rendering — why not Mermaid66The primary viewer is a **custom renderer**, not Mermaid. Mermaid's theming ceiling can't67express the Broomva Design System (OKLCH blue-axis, matte cards, earned glass, comet-glow)68and its dagre layout degrades on dense graphs. Instead: `elkjs` computes the layout69in-browser (pure JS → the output stays a single self-contained HTML file), and nodes are70drawn as Broomva matte cards (glass reserved for the floating detail panel, per the DS's71"glass is earned" rule). Design tokens are inlined from the Broomva Design System.72`tekton mermaid` stays ONLY as a throwaway embed/agent-legible target.7374## Roadmap (v0 → v2)75- **v0.2 (now):** YAML model · validate + lint (fitness functions) · 6 views · **on-brand76 elkjs viewer** (containment collapse/expand, as-is/to-be, click-to-trace, glass detail77 panel) · cross-tier query · Mermaid fallback embed.78- **v1:** two-way round-trip (drag/edit in the viewer → serialize back to YAML); MCP server79 (validated mutations so the agent can't emit an invalid model); vendor the full Broomva80 Design System for a React-Flow interactive canvas.81- **v2:** CRDT (loro) real-time human↔agent co-editing; live sync into Prosopon as a surface.8283## Status84v0 dogfood — internal design tool. Skillify (tested + registered) once the design loop has85been used on ≥3 real systems (rule-of-three).
broomva