Genesis Architect

The AI Software Architect that researches before it builds.
Not a scaffolding tool. A research-first AI architect that scans real production codebases,
mines their Issues for what broke, and builds your project to avoid those mistakes from commit one.

Scans 15-20 real GitHub repos, deep-analyzes the top 5-8, and mines their Issues for pitfalls -
before writing a single file.
Not a scaffolding tool. An AI Software Architect that researches before it builds.

Why Genesis Architect is different

Every other tool - create-t3-app, bolt.new, Copilot Workspace, Cookiecutter - assumes you already know what to build and how. They generate code from templates, not from evidence. They have no idea what broke in production for the 50,000 developers who built the same thing before you.

Genesis Architect treats every new project as a research problem first. It acts as a Senior Staff Engineer who spent a week studying the ecosystem before writing a single line.

You describe a vision
       ↓
Genesis scans 15-20 real repos, deeply analyzes top 5-8
       ↓
It mines their GitHub Issues for what broke in production
       ↓
It builds a scaffold that avoids those mistakes
       ↓
Three security gates activate on the first commit: secret scanning, SAST, quality gate
       ↓
It stays active as a research partner while you build

How it works

flowchart TD
    A([You describe a vision]) --> B

    subgraph P0["Phase 0 - Probe"]
        B[Detect OS, package manager\nScan nearby projects for conventions]
    end

    subgraph P1["Phase 1 - Align"]
        C[Archetype · Scale · Language\n3 focused questions]
    end

    subgraph P2["Phase 2 - Research ×3 parallel"]
        D1[Stream A\nGitHub repos]
        D2[Stream B\nExa ecosystem]
        D3[Stream C\nIssue mining]
        D1 & D2 & D3 --> E[Merge results]
    end

    subgraph P3456["Phases 3-6 - Build"]
        F[Architecture synthesis] --> G[Pitfall identification]
        G --> H[A/B architecture choice]
        H --> I[Scaffold + tests + CI\nProduction defaults + ADR\nSelf-validating smoke test]
    end

    subgraph P7["Phase 7 - Companion"]
        J[genesis help · genesis research · genesis check]
    end

    B --> C --> E --> F
    I --> J

    style P0 fill:#1e3a5f,color:#fff
    style P1 fill:#1e3a5f,color:#fff
    style P2 fill:#1a472a,color:#fff
    style P3456 fill:#4a1942,color:#fff
    style P7 fill:#7a3b00,color:#fff
    style A fill:#333,color:#fff

[!NOTE]
Three hard gates protect you: Phase 2 stops if fewer than 5 repos found. Phase 5 requires an explicit A/B/C/D choice. Phase 6 blocks git commit until the smoke test passes.

Install

# Claude Code (recommended)
git clone https://github.com/maioio-projects/genesis-architect ~/.claude/skills/genesis-architect

# Via skills.sh (any agent)
npx skills add maioio-projects/genesis-architect

# Cursor
# Copy SKILL.md to .cursor/rules/genesis-architect.md

# Codex CLI
git clone https://github.com/maioio-projects/genesis-architect ~/.codex/skills/genesis-architect

No build step, no dependencies.

Usage

genesis init a REST API in TypeScript
genesis init a Python CLI for batch image processing
genesis init a Chrome extension that does X
genesis init --from-prd PRD.md          # read a product spec, skip Phase 1
genesis init --from-team-config          # restore a teammate's research
genesis audit ./my-existing-project      # audit existing code, no scaffold
genesis harden ./my-existing-project     # inject security gates into any project

I want to build a Telegram bot
scaffold a new project for web scraping
start building a VS Code extension
I need to build a data pipeline from scratch
create a tool that converts CSV to JSON

What every project gets

Production-readiness defaults baked into every scaffold:

Languages and archetypes

Languages auto-detected from research:

TypeScript / JavaScript    Python    Go    Rust

Archetypes - each shapes the entire scaffold differently:

Why not just use X?

Works at every level of MCP setup

[!TIP]
The skill never blocks on a missing tool. It reports what it's using and continues.

Development Companion Mode

After scaffolding, Genesis Architect stays active for the rest of your session:

genesis help I need to add rate limiting      → searches Phase 2 repos for how they solved it
genesis research authentication patterns      → targeted scan with 1-3 ranked approaches
genesis check                                 → freshness audit: CVEs, outdated deps, CI versions
genesis harden ./existing-project             → inject secret scanning + SAST + quality gate into any project

In a new session, it reads RESEARCH.md from your project to restore context automatically.

Real output - not fabricated

From an actual TypeScript CLI project:

• examples/typescript-cli/RESEARCH.md - 17 repos analyzed, every source linked
• examples/typescript-cli/PITFALLS.md - 4 real pitfalls from GitHub Issues, mitigations built into the scaffold
• examples/typescript-cli/ROADMAP.md - 5-phase plan calibrated to what the research found

Project structure

genesis-architect/
├── SKILL.md                        # Skill definition (400 lines)
├── plugin.json                     # Marketplace manifest
├── scripts/
│   ├── scaffold_generator.py       # Creates project structure from language + tier
│   ├── research_validator.py       # Validates RESEARCH.md has all required sections
│   └── eval_runner.py              # Measures trigger rate (target: ≥90%)
├── evals/
│   ├── test_queries.json           # 36 trigger/no-trigger test cases (100% accuracy)
│   └── README.md
├── examples/
│   └── typescript-cli/             # Real output from a real project
│       ├── RESEARCH.md
│       ├── PITFALLS.md
│       └── ROADMAP.md
├── assets/
│   ├── RESEARCH.template.md        # Source of truth for validator
│   ├── PITFALLS.template.md
│   └── ROADMAP.template.md
├── references/
│   ├── architecture-patterns.md    # Boilerplate per language/tier + production defaults
│   ├── mcp-strategy.md             # MCP tool strategy and fallback logic
│   └── security-templates.md       # secret scanning, SAST, quality gate, pre-commit templates
├── .github/
│   └── workflows/
│       └── ci.yml                  # Tests, secret scanning, SAST, quality gate (4 parallel jobs)
├── CHANGELOG.md
└── CONTRIBUTING.md

Quality Score

Measured against the quality rubric (100-point, 4 dimensions):

Average: 78/100 (measured on v2.0.0 release). Primary gap: Section 4 (Phase Correctness) requires session transcripts for full scoring. Go/Rust scaffold parity with TypeScript/Python added in v2.1.0.

Quality Shield

Four independent CI jobs run on every push and pull request:

To activate: add SNYK_TOKEN and SONAR_TOKEN in repository Settings > Secrets and variables > Actions. Secret scanning works out of the box on public repos.

[!IMPORTANT]
After connecting SonarCloud, disable Automatic Analysis in the SonarCloud project settings (Project Settings > Analysis Method). Running both Automatic Analysis and CI-based analysis simultaneously causes the quality-gate job to fail with a conflict error.

Badge	Meaning
	No high/critical CVEs in Python deps
	Code quality gate status
	Security rating (A = best)
	Maintainability rating
	All 4 CI jobs passing

_{Built on open-source security tooling. See security-templates.md for implementation details.}

Roadmap

Community contributions welcome - see CONTRIBUTING.md.

Honest Limitations

Community

Genesis Architect improves through real-world use.

• Share your output: open a PR adding your RESEARCH.md and PITFALLS.md to examples/
• Report missed pitfalls: if something slipped past the research phase, open an issue - it becomes a future mitigation
• Good first issues: check the good first issue label to start contributing
• Fork intelligence: Genesis Architect scans forks of researched repos for patches not yet merged upstream - your fork improvements may automatically flow back into future scaffolds

Open an issue | Submit a PR | Discussions

Support this project

Genesis Architect is free and open-source. If it saved you from a bad architecture decision, a production incident, or hours of research - consider supporting continued development:

Sponsorship funds: additional language templates, deeper MCP integrations, real-world example projects, and VS Code extension development.

Contributing

See CONTRIBUTING.md.

New language templates, improved MCP strategies, and workflow refinements are welcome.

[!IMPORTANT]
Keep SKILL.md under 400 lines. No em dashes anywhere. All code, filenames, and comments in English.

[!NOTE]
This project is part of a portfolio demonstrating production-grade AI skill engineering: research-driven scaffolding, self-validating output, multi-layer quality gates, and measurable outcome quality. View all projects

License

MIT - Maio Eshet