convez.ai
SkillProdutividadeIntermediário
maioio

Genesis Architect

maioio/genesis-architect

Scaffold inteligente que aprende com falhas de outros projetos

Ver no GitHub
BomPluginScore · de 0 a 100

Skill que escaneia GitHub Issues antes de gerar scaffolds de projeto, minerando falhas reais e padrões de erro em repositórios similares. Gera código inicial com mitigações contra armadilhas comuns já incorporadas, economizando arquitetura ruim desde o primeiro commit.

Instalação

$npx convez-ai maioio/genesis-architect

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
49
Forks
7
Acompanhando
2
Saúde
85%
Último commit
há 5 dias
Versão
v9.0.0
Issues abertas
19
Contribuidores
3

Casos de uso

  • Gerar estrutura inicial de projetos Python com padrões já testados
  • Evitar armadilhas arquiteturais comuns minerando GitHub Issues
  • Acelerar ramp-up de novos projetos com boas práticas embutidas

Veredito

Genesis Architect é uma skill bem-executada que transforma dados públicos em scaffolds mais resilientes. Reduz decisões arquiteturais ruins ao aprender com falhas reais, especialmente útil para equipes que querem evitar repetir erros conhecidos em Python.

README

A tradução para o português deste README ainda está na fila.

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.

CI Version License Claude Code Known Vulnerabilities

Quality Gate Security Rating Maintainability Coverage

Phases Languages Archetypes Tests Eval accuracy Stars

GitHub Sponsors Buy Me a Coffee

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


What it actually produces

Run: genesis init a Python CLI for analyzing log files

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

#IssueFound inRoot causeBuilt-in mitigation
1pallets/click#24164/5 reposBusiness logic inside Click callback - untestablecli.py only parses args, all logic in core.py
2pallets/click#25583/5 reposType stubs change in Click 8.1.4 breaks mypy silentlyPin click>=8.1.7, # type: ignore only where needed
3pallets/click#18463/5 reposRaw file path from CLI args allows ../../../etc/passwdget_safe_path(base, user_input) in utils/security.py
4fastapi/typer#5225/5 reposNo input validation produces cryptic tracebacks as errorsclick.BadParameter at entry point before any processing

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.


When NOT to use Genesis

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

Install

# 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.


Usage

# 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

How it works

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.


Fast MVP mode

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.


Development Partner Mode

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.

Experience Selection

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.

Question format for major decisions

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.

What Genesis asks before vs. what it decides alone

Genesis MUST ask beforeGenesis decides alone
Architecture: Minimalist vs ScalableFile names
MVP scope: what is in / what is outFolder structure details
Technology: when tradeoffs are realFormatting and linting choices
Product direction: target user, pivotsSmall implementation details
Business: monetization, open vs commercialInternal refactors

Companion Mode stays active

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


What every project gets

DeliverableContents
RESEARCH.md15-20 repos scanned, top repos deeply analyzed, sources linked
PITFALLS.md3-7 real pitfalls from GitHub Issues with root causes and mitigations
ROADMAP.md5-10 phase development plan
src/Functional code - not empty stubs
tests/Passing unit tests for core logic
.github/workflows/ci.yml4 parallel jobs: tests, secret scanning, SAST, code quality gate
utils/security.py or security.tsget_safe_path guard for all file I/O (when applicable)
docs/adr/001-initial-architecture.mdEvery architectural decision explained with evidence
.gitignoreLanguage-appropriate, hardened against secrets and build artifacts
.pre-commit-config.yamlGenesis enforcement hooks: mitigation enforcer + drift detector

Production defaults baked into every scaffold:

DefaultWhat it does
Structured loggingpino/winston/slog from line 1 - no console.log in production
Non-root DockerfileUSER 1001 - never runs as root
Env validationFails loudly at startup if required vars are missing
GET /healthReturns {"status":"ok"} (Web Service archetype)
No wildcard CORSExplicitly listed origins only
Secret Zero.env.example with generation hint, validated at startup
Secret scanning CIEvery push scanned - build fails on exposed credentials
SAST analysis CIStatic analysis catches injection and path traversal on every push

How it compares

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.

CapabilityGenesis Architectcreate-t3-appbolt.newCursor Rules
Research from real GitHub IssuesYesNoNoNo
Validates citations (no hallucinated repos)Yesn/aNon/a
Hard gates before file creationYesNoNoNo
Development Partner Mode (asks before major decisions)YesNoNoNo
Secret scanning + SAST on every scaffoldYesNoNoNo
Retrofit security into existing projectsYesNoNoNo
Smart Resolution Engine with local vaultYesNoNoNo
Stays active for entire project lifecycleYesNoNoNo

Assessments based on public documentation as of 2026.


Works at every level of MCP setup

SetupResearch qualitySpeed
No MCPsWeb search - real repos, shallower issue dataNormal
GitHub MCPDeep repo scan + real Issue extractionNormal
GitHub + ExaFull parallel: repos + Reddit/HN/SO context~3x faster
GitHub + Exa + FirecrawlFull parallel + targeted page scraping~3x faster

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


Smart Resolution Engine

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.


Development Companion Mode

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 and archetypes

Languages auto-detected from research:

TypeScript / JavaScript    Python    Go    Rust

Archetypes - each shapes the entire scaffold differently:

ArchetypeEntrypointHas serverHas DockerfileTest runner
CLI Toolbin / [project.scripts]NoOptionalpytest / jest
Library/SDKPublic API, no main()NoNopytest / jest
Web Service/APIRouterYesYes + /healthpytest / jest
Frontend AppComponent treeNo (SSR optional)Optionalvitest / jest

Real output - not fabricated

From actual projects:

TypeScript CLI:

Python CLI:


What contributors found

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.


Honest Limitations

LimitationDetails
Issue mining depthScans up to 50 most-recent issues across repos. Low-traffic projects or old issues may not surface.
Web-search-only modeWithout GitHub MCP, issue extraction is shallow. RESEARCH.md will note this automatically.
Stack Overflow API limit300 requests/day unauthenticated. Set STACKOVERFLOW_KEY for 10,000/day. Vault hits bypass this entirely.
Fork intelligenceScanning active forks for upstream patches requires GitHub MCP. Without it, fork analysis is skipped.
WSLOn Windows inside WSL, Linux paths and package managers are used - Windows PATH fixes do not apply.

Project structure

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

Quality Shield

Four CI jobs run on every push and pull request:

JobWhat it gatesSecret required
quality-gates372 unit tests, evidence pack generation, mitigation enforcement, drift detection, scaffold smoke test, SKILL.md constraintsGITHUB_TOKEN (built-in)
secrets-scanExposed credentials, API keys, tokens in every commitnone
sonarcloudMaintainability, Reliability, Security Hotspots; skips if SONAR_TOKEN absentSONAR_TOKEN
security-scanDependency CVEs (HIGH+) via Snyk; skips if SNYK_TOKEN absentSNYK_TOKEN

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)

[!IMPORTANT] After connecting SonarCloud, disable Automatic Analysis in SonarCloud project settings. Running both simultaneously causes the quality-gate job to fail.


Roadmap

PriorityFeatureStatus
1Demo GIFPending
2Go and Rust real-world example projectsIn progress
3Benchmark report: Genesis vs plain Claude on real projectsPlanned
4Interactive CLI with progress barsPlanned
5VS Code extensionPlanned

Community contributions welcome - see CONTRIBUTING.md.


Community

  • 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


Support this project

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

GitHub Sponsors Buy Me a Coffee


Contributing

See CONTRIBUTING.md.

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

License

MIT - Maio Eshet


Star this repo if Genesis Architect saved you from a bad architecture decision. It helps others find it.

Issues · Discussions · CHANGELOG

Ver o original no GitHub

Bom para

Relacionados