genesis-architect

---
name: genesis-architect
description: >
  Use when starting a new project - scans 15-20 real GitHub repos and mines their Issues for
  pitfalls before writing a single file. No other scaffolding tool does this automatically.
  Identifies real architecture regrets from production codebases, then builds a working scaffold
  with tests, CI/CD, security defaults, and an ADR explaining every decision. After scaffolding,
  stays active as a research companion. Triggers on: "genesis init [vision]", "I want to build
  X", "scaffold", "new project", "set up project", "start building", "create a tool", "make a
  CLI", "bootstrap", "בנה פרויקט", "צור פרויקט", "התחל פרויקט".
---

<!--
Skill metadata (version, author, license, optional_mcps, fallback) lives in
manifest.json and plugin.json. Claude Code only reads `name` and `description`
from this frontmatter; extra keys are silently ignored, so they belong with
the rest of the package metadata, not here.
-->


# 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. Detect shell: if `$PSVersionTable` is accessible = PowerShell; otherwise = CMD.
After any `pip install -e .`, run the installed command immediately. If "not recognized": session fix `$env:PATH += ";[Scripts path]"` (PS) or `set PATH=%PATH%;[Scripts path]` (CMD); permanent fix `[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";[Scripts path]", "User")`.

**WSL note**: when `wsl == true`, treat as Linux - skip Windows PATH fixes entirely.

---

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

| Situation | Action |
|-----------|--------|
| 0 repos | Architect Mode - note "first-principles design" in RESEARCH.md |
| Active forks | Analyze top 3 forks, incorporate fixes |
| 1-11 repos | Floor not met - present A/B/C above, wait for user choice |
| 12+ repos, 5+ deep | Floor met - write phase-2-research.json, continue |
| API timeout / MCP unavailable | Report briefly, switch to web search fallback |

---

## 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 write-phase3-validation .`

**The Wise Average**: do not copy one project. Synthesize: most common folder structure (ecosystem convergence) + highest-rated project's structural decisions (quality signal).

**Language confirmation**: Present auto-detected language before proceeding:
"Detected: [LANGUAGE]. Continue? A: Yes  B: Different language  C: You decide"

**Windows check**: If OS is Windows (from Phase 0), automatically add to the pitfall watchlist:
- Unicode/encoding issues in CLI output tools (rich, click, curses)
- Path separator differences (`\` vs `/`)
- Filesystem-illegal characters more restrictive on Windows (`:`, `*`, `?`, `"`)

---

## Phase 4: Pitfall Identification

Compile top pitfalls from the issue scan. For each: **What** (problem), **Where** (full URL `https://github.com/[owner]/[repo]/issues/[number]`), **Why** (root cause), **Mitigation** (what we build differently), **mitigation_file_path** (scaffold path - required). Aim for 3-7.

**Phase 2 -> Phase 3 gate** (run immediately after writing PITFALLS.md):
`python scripts/research_validator.py PITFALLS.md --validate-pitfalls [--verify-issues]`
Rejects pitfalls without a live Issue URL or unmapped mitigation_file_path. Fix or drop before Phase 5.
If `GITHUB_TOKEN` set: all URLs verified. Otherwise first 3 checked via web fetch.

**Platform risks**: Every platform/archetype-specific risk (e.g., Windows console encoding, path separators) must appear in PITFALLS.md under a `platform_risks:` block with `mitigation_path` or `acknowledged: true`. Run after PITFALLS.md: `python scripts/pitfall_coverage_check.py PITFALLS.md src/ --check-platform-risks`

Before proceeding to Phase 5, compute and display a one-line **Research Quality Signal**:

| Condition | Label |
|-----------|-------|
| GitHub MCP available, 8+ repos deep-analyzed, 5+ issues found | `FULL` |
| GitHub MCP unavailable OR 5-7 repos analyzed OR 2-4 issues found | `PARTIAL` |
| Web search only, fewer than 5 repos, or 0-1 issues found | `THIN` |

Display as: `Research quality: [LABEL] ([brief reason])`. THIN does not block - the user sees it and decides.

---

## Phase 5: Interactive Choice

**Prerequisite gates** (check before rendering this phase):
1. `python scripts/genesis_state.py require-phase2 .` - aborts if Phase 2 floor not met
2. PITFALLS.md passed `--validate-pitfalls` check in Phase 4
3. `python scripts/pitfall_coverage_check.py PITFALLS.md src/ --check-platform-risks` - all mitigations and platform risks accounted for

**Archetype confirmation** (run only when Phase 1 was skipped via `genesis init`):
> "Detected: [Archetype] / [Scale] / [Language]. Correct? [Y / correct me]"
Wait for reply. If user corrects any field, update and proceed. Skip when Phase 1 ran normally.

Present research summary and architectural options in a **single message** containing all of the following sections in order:

**Section 1 - Research summary**: repo table (project, stars, key insight), Ecosystem Velocity signals, convention match question (from Phase 0).

**Section 2 - Pitfall annotations (required)**: For each pitfall in PITFALLS.md, note which option mitigates it and which accepts the risk. Example: "Pitfall 2 (memory leak): Scalable mitigates via worker isolation / Minimalist accepts this risk." If PITFALLS.md is missing or empty: "No pitfalls found - architecture choice is unaided."

**Section 3 - Architecture options**: Load trees from `references/folder-structures.toml`. Every tree must include production defaults:
- `src/<pkg>/utils/security.py` (language equivalent), `.env.example`, `.pre-commit-config.yaml`, `sonar-project.properties`, `docs/adr/001-initial-architecture.md`, `RESEARCH.md`, `PITFALLS.md`, `ROADMAP.md`
- `.github/workflows/ci.yml` with comment: `# Jobs: quality-gates (always) | secrets-scan (always) | sonarcloud (SONAR_TOKEN) | security-scan (SNYK_TOKEN)`

**A: Minimalist** - TOML minimalist tier. Best for personal/prototype.
**B: Scalable** - TOML scalable tier. Best for team/long-term.
**C: Let research decide** - highest-starred repo structure, state reasoning.
**D: Hybrid** - ask base (A or B) then what to change, confirm before building.

**Section 4 - Inline doc previews (required)**: Before the A/B/C/D prompt, show real content:
- **RESEARCH.md**: Executive Summary + first 3 repo rows from the Analyzed Repositories table
- **PITFALLS.md**: all pitfall names, mitigation_file_path, and issue URL for each
- **ROADMAP.md**: all phase names and one-line descriptions

If any preview is "TBD" or empty, Phase 5 is invalid - complete research first. On success, run in order:
`python scripts/genesis_state.py write-phase5-previews . --research --pitfalls --roadmap`
`python scripts/evidence_pack.py generate --project-dir .` (writes ARCHITECTURE_EVIDENCE.md + .genesis/evidence.json)
`python scripts/genesis_state.py write-evidence-pack . --pitfall-count N --mapped-count M` (gates Phase 6)

**Section 5 - Phase 6 smoke gate**: Show the exact command Phase 6 must pass:
`python scripts/scaffold_smoke_test.py --archetype [archetype] --entrypoint [name] --print-only`

**Section 6 - Companion Mode handoff** (required at end of Phase 5 message):
> "Companion Mode active after scaffold. Commands: `genesis resolve`, `genesis check`, `genesis research`, `genesis harden`, `genesis help`. Cache: `.genesis/vault/`."

**Hard gate**: user must confirm one of A, B, C, or D. Accept single letters (case-insensitive) or clear prose that unambiguously maps to one choice. If the prose is ambiguous, confirm: "I'll take that as [X] - correct?" and proceed on yes. After 3 unresolvable responses, ask: 'Start over from Phase 1? [Y/N]'. Do not start Phase 6 until confirmed.

---

## Phase 6: The Genesis Build

Build in this exact order. Announce each step.

### Step 0: Evidence gate (mandatory)
`python scripts/genesis_state.py require-evidence-pack .` - exits non-zero if ARCHITECTURE_EVIDENCE.md is missing or any pitfall lacks a mitigation_file_path. Abort Phase 6 until this passes.

### Step 1: File structure (automatic)
Create all directories and files including `.gitignore`. Non-destructive - no approval needed. Announce: "Creating folder structure..."
Always create `.genesis/vault/` with a `README.md` explaining: "Smart Resolution Engine cache. Use `genesis resolve [topic]` to query. Solutions cached here avoid external API calls."
If project uses .env: after creating `.env.example`, ask: "Configure .env now? I'll ask for key values." Fill interactively - never leave the user with only `.env.example`.

### Step 2: Approval gates (always ask before running)
Show what will happen, wait for explicit yes/no: `npm install`/`pip install` ("Download project dependencies? ([X] packages)"), any docker command ("Start Docker services?").
After install on Windows: run `[entrypoint] --help`. If not found, provide session fix (`$env:PATH += ";[Scripts path]"`) and permanent fix (`[Environment]::SetEnvironmentVariable(...)`).
Never run `git push` or send code to a remote without explicit user approval. `git remote add` only when user provides URL and confirms.

### Step 3: Functional boilerplate
Every file must contain working code, not empty stubs. Requirements: at least one function or class with real basic logic, engineering decision comment on any non-obvious structure choice.

Comment format:
```
# Architecture note: [decision] (inspired by [repo-url])
# Avoids: [specific pitfall from PITFALLS.md #N]
```

### Step 3b: Production-readiness defaults (always included)
Non-retrofittable defaults for every scaffold (details in `references/architecture-patterns.md` under "Production-Readiness Defaults"):
- **Structured logging**: pino/winston (Node), stdlib logging (Python), slog (Go)
- **Security**: non-root Dockerfile user, no wildcard CORS, Secure+HttpOnly cookies
- **Env validation**: fail at startup if required env vars are missing - never silently
- **Secret Zero**: `.env.example` with `SECRET_KEY=change-me-generate-with-openssl-rand-hex-32`
- **Health endpoint** (Web Service only): `GET /health` returning `{"status":"ok"}`
- **ADR stub**: `docs/adr/001-initial-architecture.md` - key decisions, links to RESEARCH.md
- **Secret leak protection**: secret-scanning CI job in `ci.yml` - fails build on exposed credentials
- **Dependency and SAST scan**: static analysis CI job in `ci.yml` - catches injection and path traversal vulnerabilities
- **Quality gate**: `sonar-project.properties` ready; add `SONAR_TOKEN` to GitHub Secrets to activate the quality badge and merge gate
- **Path traversal guard**: inject `_safe_path` (from `references/architecture-patterns.md`) when the project handles user-supplied file paths (CLI tools, file processors, upload endpoints); skip for pure API services or frontends

**Web Service archetype only**: create `endpoint-inventory.json` with `[{"method":"GET","path":"/health","added_in":"scaffold"}]`. `genesis check` uses this to detect API surface drift after 30+ days.

### Step 4: Tests
Create `tests/` with: minimum 1 unit test that actually passes (not `assert True`), test config file (jest.config.js, pytest.ini, pyproject.toml, etc.), tested function must be the core function of the project.

### Step 5: GitHub Actions CI/CD
Create `.github/workflows/ci.yml` using the language-specific template from `references/architecture-patterns.md`.
The template includes four parallel jobs: `test`, `secrets-scan`, `sast`, `quality-gate`.
The `quality-gate` job activates automatically once `SONAR_TOKEN` is added to GitHub Secrets.
Note: after creating the project in SonarCloud, disable "Automatic Analysis" in the SonarCloud project settings - CI-based analysis and Automatic Analysis conflict.

### Step 6: Self-validating smoke test (mandatory)

Run the test suite. Fix failures. Repeat until green. Never skip.
Run `pytest` / `npm test` / `cargo test` / `go test ./...`. If exit 0: proceed.
If non-zero: read error, fix the failing file, retry - max 3 attempts.
After 3 failures: report exact error, ask user before proceeding. Never commit on red.

After tests pass, run the archetype smoke test defined in Phase 5:
`python scripts/scaffold_smoke_test.py --archetype [archetype] --entrypoint [name] --run`
Record the result: `python scripts/genesis_state.py write-phase6-smoke . --archetype [archetype] --smoke-command "[cmd]" --exit-code [N]`

**Hard gate**: do not run `git commit` and do not announce "Genesis Architect complete" until:
1. Test suite exits 0 (write-tests-passing recorded)
2. Smoke test exits 0 (write-phase6-smoke recorded with exit_code=0)
If the test runner is not installed: report "Test runner not found - run [install command] first." Do not proceed to Step 7 without both gates green. If dependency install was declined in Step 2, skip Steps 4 and 6 and note: "Tests not run - dependencies not installed."

### Step 6.5: Mitigation enforcement (blocking gate)
`python scripts/genesis_subcommands.py validate .` - checks evidence pack + every mitigation_file_path exists on disk. Exit 1 blocks git commit. Fix missing files before Step 7. The advisory keyword-grep (pitfall_coverage_check.py) continues running in CI as a soft signal.

### Step 7: README badges, demo, and git

**Badges**: add to README.md using shields.io (see `references/architecture-patterns.md` for badge block template). Replace `{user}/{repo}` with `[github-user]/[repo-name]` if no remote exists; tell user to update on first push.
**Demo recording**: suggest `asciinema rec demo.cast` then `agg demo.cast assets/demo.gif`.
**Git setup** - always ask before each command:
1. `git init` - "Initialize Git repository?" (`.gitignore` already created in Step 1)
2. `git add . && git commit -m "feat: initial scaffold generated by Genesis Architect"`
3. Ask: "Add a GitHub remote?" - if yes: `git remote add origin [url]`, then show the
   push command but **never run it automatically**

Never commit `.env` - always commit `.env.example`.

### Step 7b: Security and Quality Hardening (automatic on every genesis init)

The four-job `ci.yml` created in Step 5 already includes secret scanning and SAST. Additionally create `sonar-project.properties` (use template from `references/security-templates.md`):
```
sonar.projectKey=[github-username]_[project-name]
sonar.organization=[github-username]
sonar.sources=src
sonar.qualitygate.wait=true
```
Announce: 'Quality gate ready. To activate: (1) add SONAR_TOKEN to GitHub Settings > Secrets, (2) disable Automatic Analysis in SonarCloud project settings.'

Create strict `.gitignore` additions (append to existing):
```
.env
.env.*
!.env.example
*.pem
*.key
*.p12
venv/
node_modules/
__pycache__/
```

Add to ROADMAP.md a Phase titled 'Activate Quality Gates' with steps: (1) Add SONAR_TOKEN secret to GitHub Settings > Secrets, (2) Add SNYK_TOKEN secret to enable dependency CVE scanning, (3) Verify first green CI run.

### Step 8: Deliver summary
Announce: "Genesis Architect complete. [bullet list of created files]. Next: [first ROADMAP phase]. Entering companion mode."

---

## Phase 7: Development Companion Mode

After Phase 6, enter companion mode. Direct invocations: `genesis help [problem]`, `genesis research [topic]`, `genesis check` (freshness audit).
**`genesis check`** - freshness audit (run 30+ days after scaffold): check deps for CVEs + CI action versions. Use OSV.dev API for deterministic CVE detection (see mcp-strategy.md). Report: CRITICAL / WARNING / INFO. Never auto-apply - show upgrade commands only.
**`genesis resolve [topic]`** - Smart Resolution Engine: checks local Knowledge Vault first, then fetches from Stack Overflow. Prioritizes accepted answers and high-score results. Includes recency classification (recent: last 24 months / classic). Always shows source URL. Never patches code without explicit user confirmation.
**Knowledge Vault**: solutions are cached in `.genesis/vault/` by topic and language. Use `python scripts/vault.py search "[topic]" [language]` to query, `vault.py save` to add entries, `vault.py stats` to inspect. Vault hits avoid external API calls entirely.
**Stuck on a problem**: search Phase 2 repos first, then competing projects. Present 1-3 approaches ranked by ecosystem adoption. Cite source repo.
**Dependency question**: check last commit date, open issues trend, flag better-maintained alternatives.
**New sub-problem**: ask "Want me to search the ecosystem for how others solved this?" before scanning.
**Feature complete**: suggest updating ROADMAP.md, offer to research the next phase.
**No research context / new session**: read `RESEARCH.md` from working directory.
Extract and restore:
- Repos analyzed (Analyzed Repositories table)
- Pitfalls found (link to PITFALLS.md mitigation patterns)
- Architecture decision (Architecture Decision Rationale section)
- Language and tier chosen
Announce: 'Research context restored from RESEARCH.md - [N] repos, [M] pitfalls loaded.'
If RESEARCH.md missing: 'RESEARCH.md not found. Run genesis audit . or describe the current project.'
**Boundaries**: never act without asking first - max 3 options - stay grounded in analyzed repos, not general advice.
**Exit**: companion mode ends when the user explicitly starts a new unrelated task, uses `genesis init` for a new project, or says "done" / "exit companion mode". After exit, do not apply Genesis behavior to requests that are not about the current project.

---

## Mandatory Deliverables

All files go inside the project directory. Everything must be Git-portable.
**Privacy:** Environment-specific values from Phase 0 (Scripts paths, home directory paths, usernames embedded in paths) must appear as placeholders in deliverables: use `[Scripts path]`, `[home]`, etc. Never write the literal measured path into RESEARCH.md, PITFALLS.md, or ROADMAP.md - these files get committed to public repos.

Use templates in `assets/RESEARCH.template.md`, `assets/PITFALLS.template.md`, `assets/ROADMAP.template.md`. Required RESEARCH.md sections: Executive Summary, Search Scope, Analyzed Repositories (min 5 rows), Market Landscape, Architecture Decision Rationale, Sources (min 3 links). Must contain "Genesis Architect" in header.

---

## Architect Mode

When 0 comparable projects exist, switch to first-principles mode. Announce: "No similar projects found. Switching to Architect Mode."
Apply: SOLID, Clean Architecture, Twelve-Factor App (for services). Note in RESEARCH.md: "First-principles design - no direct ecosystem precedent found."

---

## Format Rules

- No em dashes (use hyphens or colons)
- Respond in the user's detected language
- Code, file names, variable names, comments: English only
- Prefer tables and structured lists over paragraphs
- ROADMAP.md: 5-10 phases, length calibrated to research complexity