Genesis Architect

Evidence-first architecture for real software.

Research before you build. Understand before you change.

Documentation · Getting started · Architecture · Contributing

---

Genesis researches across the software ecosystem before you build, using the sources available in the current execution environment, then turns that evidence into architecture options you approve. It mines the failures that keep recurring in comparable projects and scaffolds with those mitigations already in place. For code that already exists, it builds the import graph, scores the architecture, and reports what is fragile before anyone changes it. Every recommendation carries its sources, and nothing acts without your approval.

The sources depend on how you run it. The standalone genesis init CLI researches GitHub repositories and their issues. When Genesis runs as an agent skill, its research workflow can combine GitHub with available web and MCP sources, community discussions, package registries, security data and relevant media. Genesis's own MCP server is separate: four read-only analysis tools that do not use the network. See Research and evidence.

pip install genesis-architect

You have	Run	What happens
An idea	genesis init "a Python CLI for analyzing log files"	The CLI researches GitHub repositories and issues (an agent skill can add more sources), shows pitfalls with sources, you pick an architecture, it scaffolds
A codebase	genesis recover .	Diagnosis that leaves your source untouched: import cycles, anti-patterns, fragile modules, drift

recover needs no API key, never executes your code and does not edit your source files. It writes its own reports to .genesis/ and FRAGILITY_MAP.md in the project directory. init needs an LLM key and sends your description to GitHub and to that LLM (configuration).

Demo

A recorded, reproducible walkthrough of both flows is in demo/. The terminal output in it is captured from real runs, not written by hand.

Genesis audits itself

Genesis is run against its own source in CI. These figures are rendered from the code, and CI fails if this table drifts from the facts file.

Measured on this repository	Value
Architecture score	93 / 100
Import cycles	0
Critical anti-patterns	0
Tests collected	2,877
Engines / approval gates	19 / 14
Mapped capabilities / commands	50 / 22

Generated for v9.0.0 from data/public-product-facts.json.

The first self-audit (v9.0.0) found four import cycles and seven critical anti-patterns in Genesis itself. The method and what was fixed are in docs/architecture/overview.md.

How it works

flowchart LR
    E[Evidence] --> A[Analysis] --> D[Decision] --> P[Approval] --> X[Action] --> V[Verification]
    V -.->|re-run| E