Genesis Architect
scans 20 GitHub repos before scaffolding
Last verified:
What is Genesis Architect?
Genesis Architect is a research-first project scaffolding tool for Claude Code that scans 15-20 real GitHub repositories and mines their Issues for production failures before writing a single file of code. Unlike other scaffolding tools that generate code from generic templates, Genesis Architect identifies real architecture regrets from production codebases and builds a battle-tested scaffold that avoids those mistakes from the start.
The tool produces a complete project structure with functional boilerplate (not empty stubs), passing unit tests, GitHub Actions CI/CD with four parallel jobs (tests, secret scanning, SAST, quality gate), security defaults including path traversal guards, and comprehensive documentation including RESEARCH.md, PITFALLS.md, and ROADMAP.md. Every cited GitHub Issue URL is verified by CI - a 404 fails the build.
After scaffolding, Genesis Architect stays active as a development companion for the entire project lifecycle. It includes a Smart Resolution Engine that caches solutions in a local Knowledge Vault for instant answers without API calls, offers freshness audits checking for CVEs and outdated dependencies, and can research new sub-problems by searching the ecosystem with cited sources. It supports CLI tools, libraries/SDKs, web services/APIs, and frontend apps in TypeScript/JavaScript, Python, Go, and Rust.
Genesis Architect is for developers who want production-ready project foundations avoiding common pitfalls discovered in real-world projects. It's ideal for engineering teams building long-term maintainable projects, individual developers who want security and quality gates from day one, and anyone tired of refactoring architecture decisions made without research.
Genesis Architect pricing
Pricing model: Freemium
Genesis Architect is completely free and open-source under the MIT license. No paid tiers, subscriptions, or premium features. The tool requires no build step and has no dependencies. Stack Overflow API offers 300 requests/day free without an API key; setting STACKOVERFLOW_KEY environment variable provides 10,000 requests/day. SonarCloud quality gate and Snyk dependency scanning are optional - activate by adding SONAR_TOKEN and SNYK_TOKEN to GitHub Secrets. Sponsorship is available to fund additional language templates, deeper MCP integrations, example projects, and VS Code extension development, but all core features remain free.
Genesis Architect pros
- Scans 15-20 real GitHub repos before scaffolding - no other tool does this automatically
- Mines GitHub Issues for recurring production failures and architecture regrets
- Every cited Issue URL verified by CI - 404 fails the build preventing hallucinated sources
- Generates functional boilerplate with real logic, not empty stubs
- Includes 4 parallel CI jobs: tests, secret scanning, SAST, and code quality gate
- Smart Resolution Engine with local Knowledge Vault for instant answers without API calls
- Built-in path traversal guard (get_safe_path) for projects handling user file paths
- Production-readiness defaults: structured logging, non-root Dockerfile, env validation, health endpoint
- Research Quality Signal (FULL/PARTIAL/THIN) transparently shows research depth
- Hard gates prevent file creation until research floor met and user confirms architecture choice
- Stays active as companion for entire project lifecycle, not just one-time scaffold
- Supports --from-prd to read product specs and skip Phase 1 questions
- Detects active forks and incorporates bug fixes not yet merged upstream
- 270 unit tests with full coverage for AST enforcement, drift detection, and CLI
- Pre-commit hooks run mitigation enforcer and drift detector on every git commit
- Works without any MCP tools - web search fallback always available
- Auto-detects OS, package managers, and nearby project conventions
Genesis Architect cons
- 5-10 minute research process is overkill for quick experiments
- Issue mining limited to 100 most-recent issues across 5-8 repos - may miss older critical issues
- Web-search-only mode without GitHub MCP has shallow issue extraction
- Stack Overflow API limited to 300 requests/day unauthenticated (need key for 10,000/day)
- Requires explicit A/B/C/D architecture choice confirmation - can't auto-decide
- Windows PATH issues after pip install require manual session fix if command not recognized
- Fork intelligence for upstream patches requires GitHub MCP - skipped without it
- Low-traffic projects or niche archetypes may have fewer than 12 comparable repos found
Frequently asked questions about Genesis Architect
How is Genesis Architect different from create-t3-app, bolt.new, or Copilot Workspace?
Every other tool generates code from templates without knowing what broke in production for the 50,000 developers who built the same thing before you. Genesis Architect treats every project as a research problem first - it scans 15-20 real GitHub repos, mines their Issues for recurring failures and architecture regrets, then builds a scaffold that avoids those specific mistakes. Additionally, while other tools stop helping once the scaffold is created, Genesis Architect stays active as a development companion for the entire project lifecycle with its Smart Resolution Engine and Knowledge Vault.
What files does Genesis Architect generate?
Every project gets: RESEARCH.md (15-20 repos scanned, top 5-8 deeply analyzed with verified sources), PITFALLS.md (3-7 real pitfalls from GitHub Issues with root causes and mitigations), ROADMAP.md (5-10 phase development plan), src/ with functional boilerplate, tests/ with passing unit tests for core logic, .github/workflows/ci.yml with 4 parallel jobs, utils/security.py or security.ts with get_safe_path guard, docs/adr/001-initial-architecture.md explaining every decision, .gitignore hardened against secrets, sonar-project.properties for quality gate, and .pre-commit-config.yaml with Genesis enforcement hooks. Plus .genesis/vault/ for the Knowledge Vault cache.
What archetypes and languages does Genesis Architect support?
Genesis Architect supports four archetypes: CLI Tool (entrypoint in bin/[project.scripts], no server, optional Dockerfile), Library/SDK (public API, no main(), no server, no Dockerfile), Web Service/API (router with server, Dockerfile + /health endpoint), and Frontend App (component tree, SSR optional). Languages auto-detected from research include TypeScript/JavaScript, Python, Go, and Rust. Each archetype shapes the entire scaffold differently with appropriate test runners (pytest/jest) and production defaults.
How do I install Genesis Architect?
For Claude Code (recommended): git clone https://github.com/maioio/genesis-architect ~/.claude/skills/genesis-architect. For Cursor: copy SKILL.md to .cursor/rules/genesis-architect.md. For Codex CLI: git clone https://github.com/maioio/genesis-architect ~/.codex/skills/genesis-architect. There is no build step and no dependencies required - it works directly as a Claude skill.
What are the hard gates that prevent scaffold generation?
Genesis Architect has several enforced gates: Phase 2 stops if fewer than 12 repos with verified Issue URLs are found (floor not met), Phase 5 requires explicit A/B/C/D architecture choice confirmation before any files are created, Phase 6 blocks git commit until the smoke test exits 0 (tests pass), and evidence pack generation requires every pitfall to have a mitigation_file_path that exists on disk. The research_validator.py verifies every cited Issue URL is live - a 404 fails the build.
What is the Smart Resolution Engine and Knowledge Vault?
The Smart Resolution Engine is a two-layer system for genesis resolve [topic] queries. Layer 1 checks the local Knowledge Vault (.genesis/vault/) first - if there's a match, the answer comes back instantly with no network call or tokens consumed. Layer 2 queries the Stack Overflow API for top 3 community-verified solutions when the vault misses. Solutions are cached in the vault by topic and language for next time. The vault grows with every project, so a path traversal solution found in one project is immediately available in the next.
Can I use Genesis Architect with an existing project?
Yes. Use genesis audit ./my-existing-project to run Phases 2-4 on existing code - it delivers PITFALLS.md and RESEARCH.md without generating a scaffold. Use genesis harden ./my-existing-project to inject missing security and quality standards: secret-scanning workflow, SAST workflow, quality-gate config, strict .gitignore, and scans for common security gaps like missing input sanitization or hardcoded secrets. Both commands skip the pre-flight check since they're explicit opt-ins.
How does the research process work?
Three parallel research streams run: Stream A scans 15-20 GitHub repos matching your vision filtered by stars (>100 niche or >1k infra) and recency (<12mo), selecting top 5-8 for deep analysis. Stream B searches Reddit, Hacker News, and Stack Overflow for architecture regrets and pitfalls. Stream C mines up to 100 GitHub Issues each from the top 5-8 repos, ranked by engagement density (comments+reactions), prioritizing issues with 5+ comments or 10+ reactions and labels like bug/regression/breaking-change/security. The results merge into RESEARCH.md with verified citations and PITFALLS.md with root causes and mitigations.