Genesis Architect

Most projects fail because developers repeat mistakes that were already solved in other repositories.

Genesis Architect scans GitHub before you write code. It finds the common failures, bugs, and design pitfalls that real developers hit building the same thing - then generates a scaffold with those mitigations already built in.

If this saved you from a bad architecture decision - star it. It helps others find it.

Run: genesis init a Python CLI for analyzing log files

Pitfalls found from real GitHub Issues (before a single file is written):

Scaffold generated (12 files, 0 empty stubs):

log-analyzer/
├── src/log-analyzer/
│   ├── __init__.py
│   ├── main.py        # Click CLI - args only, delegates to core
│   ├── core.py        # All logic lives here, testable without subprocess
│   └── utils/
│       └── security.py  # get_safe_path() - path traversal guard
├── tests/
│   ├── __init__.py
│   └── test_core.py   # Tests core directly, no subprocess needed
├── .github/workflows/ci.yml  # 4 jobs: tests, secrets, SAST, quality gate
├── .env.example
├── pyproject.toml     # click>=8.1.7 pinned, mypy strict, pytest config
├── RESEARCH.md        # 5 repos analyzed, all sources verified live
├── PITFALLS.md        # The 4 pitfalls above with full root cause analysis
└── ROADMAP.md         # 5-phase plan: scaffold -> tests -> CI -> quality -> ship

Every cited issue URL is verified by CI. A 404 fails the build.

Honesty matters. Genesis is overkill for some things.

Skip Genesis if you are building:

• A tiny script (under 100 lines, no tests needed)
• A throwaway experiment or one-off utility
• A single-file tool you will delete in a week
• Something with zero external dependencies

Use Genesis if you are building:

• A project you plan to maintain for more than a month
• Anything with authentication, file I/O, or external APIs
• A library or SDK other people will depend on
• Something you want to ship without hitting the same bugs everyone else hit

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

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

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

No build step, no dependencies.

# Full research mode (default) - 15-20 repos, full Issue mining
genesis init a REST API in TypeScript
genesis init a Python CLI for batch image processing
genesis init a Chrome extension that does X

# Fast MVP mode - research capped at 5 min, then immediately builds
genesis init --fast-mvp a Discord bot in Python

# Development Partner Mode - asks before every major decision
genesis init --partner a SaaS billing system

# Read a product spec, skip the questions
genesis init --from-prd PRD.md

# Audit an existing project
genesis audit ./my-existing-project

# Inject security gates into any project
genesis harden ./my-existing-project

# Smart Resolution with local vault
genesis resolve path traversal python

Or just describe what you want:

I want to build a Telegram bot
scaffold a new project for web scraping
start building a VS Code extension

Before writing a single file, Genesis runs research across real GitHub repos:

1. Finds 15-20 repos similar to what you are building (filtered by stars, recency, language)
2. Mines GitHub Issues from the top repos - up to 50 closed issues each - extracting recurring failures, security patches, and architecture regrets
3. Synthesizes the wise average of what actually survives in production across those repos
4. Generates a scaffold where every pitfall found becomes a concrete code task - not a document to read later

The difference from templates: the scaffold reflects what broke for the people who built this before you.

genesis init --fast-mvp a REST API

Research is capped at 5 minutes, 10 repos, 30 issues. Genesis then immediately builds instead of asking questions. Output is a single BUILD_PACKET.md with each pitfall as a concrete code task, plus the full scaffold.

Use this when you want a running project in under 10 minutes and are willing to trade some research depth.

Genesis V5.1 does not make major decisions silently.

Before choosing an architecture, defining MVP scope, selecting a technology, or making a product direction call - Genesis presents options, explains the tradeoff, and waits.

The rule: fewer, better-timed questions. Not more questions. Less rework.

When you describe a project in natural language, Genesis asks once:

What kind of Genesis experience?

A: Fast Build     - quick MVP, minimal questions (hackathon / experiment)
B: Professional   - structured research and validation  [Recommended]
C: Founder        - market research, competitor analysis, product strategy
D: Auto           - Genesis infers from your description and announces its choice

Pick your mode once. Genesis adjusts research depth, question count, and output files accordingly.

When Genesis needs your input on something that matters:

Should this API use a database or in-memory state?

A: In-memory dict       - zero dependencies, no persistence across restarts
B: SQLite               - file-based, no server needed, survives restarts
C: PostgreSQL           [Recommended]
D: Let me decide later

Why C: 3 of 5 analyzed repos moved from SQLite to Postgres under load - migration cost is high.
Risk if you choose B: you will likely migrate later when concurrent writes break.
Press Enter to accept C, or type A/B/D.

Development Partner rules do not expire after the scaffold. They remain active through Phase 7 (Companion Mode) for the lifetime of the project.

Production defaults baked into every scaffold:

Every other tool - create-t3-app, bolt.new, Copilot Workspace, Cookiecutter - generates code from templates. They have no idea what broke in production for the developers who built the same thing before you.

Assessments based on public documentation as of 2026.

The skill never blocks on a missing tool. It reports what it is using and continues.

genesis resolve [topic] checks a local vault first (instant, no API call), then falls back to Stack Overflow.

$ genesis resolve "csv streaming large file python"

Smart Resolution Engine
Query: 'csv streaming large file python'
Source: Stack Overflow community answers

============================================================
Result 1: Streaming CSV from S3 to Python
  Score: 16  |  Answers: 5  |  Tags: python, boto3
  [TOP ANSWER: score 11]  [type: classic]

  Use chunked reading: read a block, find the last newline, process.
  chunk_size = 1_000_000 ...

  Source: https://stackoverflow.com/a/51142062
============================================================

IMPORTANT: Always review community solutions before applying.
Genesis Architect never patches your code without your confirmation.

Every resolved solution is saved to .genesis/vault/ and returned instantly on the next query.

No API key required (300 requests/day). Set STACKOVERFLOW_KEY for 10,000/day.

After scaffolding, Genesis 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 resolve path traversal python      -> Smart Resolution Engine with vault-first lookup

Languages auto-detected from research:

TypeScript / JavaScript    Python    Go    Rust

Archetypes - each shapes the entire scaffold differently:

From actual projects:

TypeScript CLI:

• examples/typescript-cli/RESEARCH.md - 5 repos analyzed, every source linked and verified
• examples/typescript-cli/PITFALLS.md - 4 real pitfalls from live GitHub Issues
• examples/typescript-cli/ROADMAP.md - 5-phase plan calibrated to research findings

Python CLI:

• examples/python-cli/RESEARCH.md - click, typer, python-fire, tqdm, prompt-toolkit analyzed
• examples/python-cli/PITFALLS.md - 4 pitfalls: click#2416, click#2558, tqdm#1139, typer#522 - all verified
• examples/python-cli/src/ - working Python CLI with Click, get_safe_path, and full test suite

First external contributor @nitayk opened 7 issues and submitted a 444-line PR with a self-contained code review - finding and fixing 4 bugs - within 48 hours of launch.

genesis-architect/
├── SKILL.md                        # Skill definition - the brain
├── plugin.json                     # Marketplace manifest
├── scripts/
│   ├── scaffold_generator.py       # Creates project structure
│   ├── research_validator.py       # Validates RESEARCH.md + live GitHub URL checks
│   ├── resolve_engine.py           # Smart Resolution Engine (Stack Overflow API + vault)
│   ├── vault.py                    # Knowledge Vault - local solution cache
│   ├── genesis_state.py            # Phase 5/6 hard gate state files
│   ├── genesis_subcommands.py      # genesis check: CVE scan + CI action audit
│   ├── pitfall_coverage_check.py   # Verifies PITFALLS.md mitigations exist in source
│   ├── drift_detector.py           # Architecture drift detection vs ADR baseline
│   ├── issue_miner.py              # GitHub Issue mining (GraphQL + REST)
│   ├── feedback.py                 # Pitfall feedback recorder
│   ├── env_probe.py                # Phase 0 environment detection
│   └── eval_runner.py              # Trigger rate eval + schema validation
├── tests/                          # 372 unit tests
├── evals/
│   ├── test_queries.json           # 40 trigger/no-trigger test cases (100% accuracy)
│   └── README.md
├── examples/
│   ├── typescript-cli/
│   └── python-cli/
├── references/
│   ├── architecture-patterns.md    # Boilerplate per language/tier + production defaults
│   ├── mcp-strategy.md             # MCP tool strategy and fallback logic
│   └── security-templates.md       # CI templates for secret scanning, SAST, quality gate
├── .github/
│   ├── dependabot.yml
│   └── workflows/
│       ├── ci.yml
│       └── codeql.yml
├── pyproject.toml
├── CHANGELOG.md
├── SECURITY.md
└── CONTRIBUTING.md

Four CI jobs run on every push and pull request:

To activate optional jobs: set repository Variables in Settings > Secrets and variables > Actions > Variables:

• SONAR_ENABLED = true (then add SONAR_TOKEN as a Secret)
• SNYK_ENABLED = true (then add SNYK_TOKEN as a Secret)

Community contributions welcome - see CONTRIBUTING.md.

• 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
• Good first issues: check the good first issue label

Open an issue | Submit a PR | Discussions

Genesis Architect is free and open-source. If it saved you from a bad architecture decision or production incident:

See CONTRIBUTING.md.

MIT - Maio Eshet