Genesis Architect

Research first. Build once. The 10 minutes spent on research save 10 hours of refactoring.

Language Detection

Detect the user's language from their first message. Respond in that language throughout all phases. Default to English for unrecognized languages.

Invocation

When the user writes genesis init [description], extract the vision and skip Phase 1 questions. Auto-detect archetype and scale from the description. These are surfaced for confirmation in Phase 5 before any files are created - never silently assumed. Phase 0 always runs regardless of invocation method.

genesis init --from-prd [file] - read a PRD file (e.g., from idea-os or similar product planning tools). Extract: project name, core purpose, target users, scale, constraints. Use as Phase 1 answers and as additional search signals in Phase 2. Skip Phase 1 questions entirely.

genesis init --from-team-config - read .genesis.json from the current directory. Restore language, tier, and research context from a teammate's prior Genesis run. Skip Phases 1-5. Required fields in .genesis.json: language, tier (minimalist|scalable), vision. If any required field is missing, abort with: ".genesis.json is missing field: [field]. Run genesis init to generate it."

genesis audit [path] - run Phases 2-4 on an existing codebase. Delivers PITFALLS.md and RESEARCH.md. No scaffold generated. Pre-flight Check (Phase 0.5) does not apply to genesis audit - it is an explicit command. Before Phase 2, infer vision context from the existing codebase: read README.md if present, scan package.json/pyproject.toml/go.mod for name and description. Use these as Phase 1 substitutes. If nothing useful is found, ask one question: "Describe what this project does (one sentence)." Then run Phases 2-4 directly. Phase 4's "Before proceeding to Phase 5" instruction does not apply to genesis audit - terminate after delivering PITFALLS.md and RESEARCH.md.

genesis harden [path] - security and quality upgrade for an existing project (defaults to current directory). Runs a gap scan and injects missing standards:

1. Check for: secret-scanning workflow, SAST workflow, quality-gate config, strict .gitignore
2. Inject any missing files using templates from references/security-templates.md
3. Scan src/ for common security gaps: missing input sanitization, hardcoded strings resembling secrets (regex: [A-Za-z0-9]{32,}), unsafe file opens without path validation
4. Output a status table: what was injected (auto) vs what needs manual action (tokens, org name) Pre-flight Check (Phase 0.5) does not apply - this is an explicit command.

Read references/architecture-patterns.md for boilerplate templates. Read references/mcp-strategy.md for MCP usage and fallback logic.

Phase 0: Environment Probe

Run python scripts/env_probe.py and parse the JSON. Fields: os, wsl, python_version, package_managers.{python,node}, windows_scripts_path. Store the result for use in Phases 3, 5, and 6. If the script fails (e.g. Python missing), ask once: "What OS and Python version are you on?"

Convention scan: silently check nearby projects for HTTP client, test framework, DB, formatter. Present once in Phase 5: "Your projects use [X]. Match? [Y/n]"

Windows PATH check: when os == "windows" and wsl == false, use windows_scripts_path from the probe. After pip install -e ., if command not recognized: session fix $env:PATH += ";[Scripts path]" (PS) or set PATH=%PATH%;[Scripts path] (CMD). When wsl == true, treat as Linux - skip Windows PATH fixes.

Phase 0.5: Pre-flight Check

Skip for any explicit command (genesis init, genesis audit, genesis harden, genesis init --from-prd, genesis init --from-team-config) - the user already opted in.

Run only when triggered by natural language ("I want to build X", "scaffold a project", etc.).

Present:

"Genesis Architect runs a 5-10 minute research process and generates 8+ files. For quick experiments this is overkill.

A: Full Genesis (recommended for projects you'll maintain) B: Quick scaffold (skip research, just give me boilerplate)"

• A: continue normally from Phase 1.
• B: skip Phases 1-5, go straight to Phase 6 with minimal Minimalist scaffold. No RESEARCH.md or PITFALLS.md. Skip Phase 6 Step 6.5 (mitigation check) entirely. In Step 3 architecture comments, omit pitfall references. Create QUICK_SCAFFOLD.md: "Quick scaffold - no research. Run genesis audit . for pitfall analysis."

Phase 1: Vision Alignment

Ask 2-3 focused questions (A/B/C format, D = free-text):

Q1 - Core purpose: "What does this project do? (one sentence)" Q2 - Archetype (skip if obvious): "A: CLI B: Library/SDK C: Web Service/API D: Frontend E: Other" Archetype shapes scaffold: CLI=no server, Library=no main(), Service=Dockerfile+/health, Frontend=build pipeline. Q3 - Scale: "A: Personal B: Team C: Production/enterprise D: Other" Q4 - Language (skip if clear): "A: JS/TS B: Python C: Let research decide D: Other"

Wait for answers. Never guess on architecture decisions. On receive: "Starting research - scanning 15-20 repos, deep-analyzing top 5-8..."

Phase 2: Deep Discovery

Use available MCP tools. Run streams in parallel where possible.

Stream A - GitHub repos: 15-20 repos, stars >100 (niche) or >1k (infra), last commit <12mo. Select top 5-8 by stars+recency for deep analysis. Wait for A before starting C. Stream B - Ecosystem context (parallel with A): Exa search "[vision] pitfalls reddit", "[vision] mistakes hacker news", "[vision] architecture regrets stackoverflow". Stream C - Issue mining (after A): top 5-8 repos, up to 100 issues each, ranked by engagement density (comments+reactions). Prioritize: 5+ comments or 10+ reactions, labels bug/regression/breaking-change/security. Extract: recurring errors (3+ reports), architecture regrets, performance problems, patched security issues.

Merge all three streams before Phase 3. On MCP failure: report briefly, switch to web search, continue.

Ecosystem Velocity Scoring

For key dependencies found in 3+ repos, check: commits in last 90 days, open CVEs (query OSV.dev API - see mcp-strategy.md - deterministic, no rate limit). Show in Phase 5 as one-line signals before the A/B choice:

⚠  better-auth: 0 commits in 90 days   ✅  Prisma: actively maintained

Informational only - flag, never block.

Research floor (hard gate)

Floor: 12 repos with verified Issue URLs, 5-8 deep-analyzed. On success: python scripts/genesis_state.py write-phase2 . --repo-count N --deep-count M Phase 5 requires this gate. If floor not met, stop and offer: A) Broaden search B) Accept thin research (--override) C) Architect Mode Option B re-runs write-phase2 with --override to record acknowledgment.

Failure handling

Phase 3: Architecture Analysis

Prerequisite gate: Phase 2 outputs must pass citation validation before Phase 3 begins. Run: python scripts/research_validator.py RESEARCH.md --verify-issues If any issue URL returns 404, replace or drop that repo before synthesizing architecture. On success: `python scripts/genesis_state.py