# alvindemesadev/boring-engineering architecture

> Architecture diagram of the GitHub repository alvindemesadev/boring-engineering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alvindemesadev/boring-engineering
- Repository: https://github.com/alvindemesadev/boring-engineering

## Overview

boring-engineering is an Agent Skills-compatible guidance package, not a runtime application. An agent discovers and activates `SKILL.md` for coding tasks, applies its four-step decision system, and may load the decision tree or deeper principle references on demand. The README also documents before/after examples as supporting guidance. Source excerpts were unavailable, so edges reflect only relationships explicitly described in the README.

Main entry points: [`SKILL.md`](https://github.com/alvindemesadev/boring-engineering/blob/main/SKILL.md) (Core skill), [`assets/decision-tree.md`](https://github.com/alvindemesadev/boring-engineering/blob/main/assets/decision-tree.md) (Decision tree), [`references/decision-framework.md`](https://github.com/alvindemesadev/boring-engineering/blob/main/references/decision-framework.md) (Decision framework), [`references/kiss.md`](https://github.com/alvindemesadev/boring-engineering/blob/main/references/kiss.md) (KISS guidance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skill["Skill workflow"]
  node_skill_doc["Core skill<br/>[SKILL.md]"]
end

subgraph group_references["Decision references"]
  node_decision_tree["Decision tree<br/>[decision-tree.md]"]
  node_framework["Decision framework"]
  node_kiss["KISS guidance<br/>[kiss.md]"]
  node_yagni["YAGNI guidance<br/>[yagni.md]"]
  node_dry["Practical DRY<br/>[dry.md]"]
end

subgraph group_examples["Examples"]
  node_bad_examples["Anti-patterns"]
  node_good_examples["Good patterns"]
  node_comparisons["Refactoring examples<br/>[before-after.md]"]
end

node_agent(("AI agent"))

node_agent -->|"loads on activation"| node_skill_doc
node_skill_doc -->|"loads on demand"| node_decision_tree
node_skill_doc -->|"loads on demand"| node_framework
node_skill_doc -->|"references"| node_kiss
node_skill_doc -->|"references"| node_yagni
node_skill_doc -->|"references"| node_dry
node_agent -->|"consults examples"| node_bad_examples
node_agent -->|"consults examples"| node_good_examples
node_agent -->|"consults examples"| node_comparisons

click node_skill_doc "https://github.com/alvindemesadev/boring-engineering/blob/main/SKILL.md"
click node_decision_tree "https://github.com/alvindemesadev/boring-engineering/blob/main/assets/decision-tree.md"
click node_framework "https://github.com/alvindemesadev/boring-engineering/blob/main/references/decision-framework.md"
click node_kiss "https://github.com/alvindemesadev/boring-engineering/blob/main/references/kiss.md"
click node_yagni "https://github.com/alvindemesadev/boring-engineering/blob/main/references/yagni.md"
click node_dry "https://github.com/alvindemesadev/boring-engineering/blob/main/references/dry.md"
click node_bad_examples "https://github.com/alvindemesadev/boring-engineering/blob/main/examples/bad-abstractions.md"
click node_good_examples "https://github.com/alvindemesadev/boring-engineering/blob/main/examples/good-abstractions.md"
click node_comparisons "https://github.com/alvindemesadev/boring-engineering/blob/main/examples/before-after.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_doc toneBlue
class node_decision_tree,node_framework,node_kiss,node_yagni,node_dry toneAmber
class node_bad_examples,node_good_examples,node_comparisons toneMint
class node_agent toneIndigo
```

## Components

### Skill workflow

- [Core skill](https://github.com/alvindemesadev/boring-engineering/blob/main/SKILL.md): `SKILL.md`

### Decision references

- [Decision tree](https://github.com/alvindemesadev/boring-engineering/blob/main/assets/decision-tree.md): `assets/decision-tree.md`
- [Decision framework](https://github.com/alvindemesadev/boring-engineering/blob/main/references/decision-framework.md): `references/decision-framework.md`
- [KISS guidance](https://github.com/alvindemesadev/boring-engineering/blob/main/references/kiss.md): `references/kiss.md`
- [YAGNI guidance](https://github.com/alvindemesadev/boring-engineering/blob/main/references/yagni.md): `references/yagni.md`
- [Practical DRY](https://github.com/alvindemesadev/boring-engineering/blob/main/references/dry.md): `references/dry.md`

### Examples

- [Anti-patterns](https://github.com/alvindemesadev/boring-engineering/blob/main/examples/bad-abstractions.md): `examples/bad-abstractions.md`
- [Good patterns](https://github.com/alvindemesadev/boring-engineering/blob/main/examples/good-abstractions.md): `examples/good-abstractions.md`
- [Refactoring examples](https://github.com/alvindemesadev/boring-engineering/blob/main/examples/before-after.md): `examples/before-after.md`

### Other components

- **AI agent**

## Connections

- AI agent → Core skill: loads on activation (evidence: `README.md`)
- Core skill → Decision tree: loads on demand (evidence: `README.md`)
- Core skill → Decision framework: loads on demand (evidence: `README.md`)
- Core skill → KISS guidance: references (evidence: `README.md`)
- Core skill → YAGNI guidance: references (evidence: `README.md`)
- Core skill → Practical DRY: references (evidence: `README.md`)
- AI agent → Anti-patterns: consults examples (evidence: `README.md`)
- AI agent → Good patterns: consults examples (evidence: `README.md`)
- AI agent → Refactoring examples: consults examples (evidence: `README.md`)
