tekton

name	tekton
category	design
description	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); implementation itself. Triggers on: design architecture, model the system, user journey, data model, tekton.
license	MIT
metadata	{"version":"0.2.0","homepage":"https://broomva.tech/skills/tekton"}
primitive	null
required	false

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.