v3.1.1 - pip install fix

Fixed

• pyproject.toml: corrected build backend (setuptools.build_meta) so pip install genesis-architect works correctly
• Script shims now re-export required symbols for CI evidence pack check
• Removed em dashes from all tracked files to pass CI gate
• SELF_PITFALLS.md: updated mitigation file paths to point to src/ after scripts migration

This is a patch release with no behaviour changes.

v3.0.0 — The Standalone & Smart Research Update

Genesis Architect v3.0.0 — "The Standalone & Smart Research Update"

Research first. Build once. Now from anywhere.

This is the biggest release since Genesis was born. We went from a Claude Code-only skill to a fully standalone, pip-installable CLI — and we rebuilt the research engine from the ground up with four new intelligence layers. If you've been waiting to share Genesis with teammates who don't use Claude Code, today is that day.

---

🚀 Major Features

1. Standalone CLI — pip install genesis-architect

Genesis is no longer tied to Claude Code. Install it once, run it anywhere.

pip install genesis-architect
genesis config set LLM_API_KEY your-key
genesis init "a FastAPI task queue with Celery and Redis"

Works with Claude, GPT-4, Gemini, Ollama — any provider supported by LiteLLM. One command to configure, one command to build. No Claude Code required, no skill directory, no setup ceremony.

This multiplies the potential audience by 50x. Every Python developer on every machine can now use Genesis.

---

2. Self-Healing Knowledge Vault

Genesis now remembers solutions between runs.

Every Stack Overflow answer and resolved pitfall gets cached in .genesis/vault/index.json with:

• 6-month TTL — stale entries are flagged and refreshed automatically on the next run
• LRU eviction at 500 entries — the least-recently-used solutions are dropped when capacity is reached
• Stale fallback — if the network is unavailable and the cache is stale, Genesis returns the old solution with a visible warning rather than crashing

Repeat projects run faster. Offline projects still work. No solution is ever silently outdated.

---

3. Smart Fork Analysis — Ranked by Activity, Not Hype

Genesis now finds the top 3 active forks of every analyzed repo — and it ranks them by merged PRs in the last 6 months, not by star count.

A fork with 10 stars but 12 merged PRs this quarter beats one with 500 stars and no recent activity. Those merged PRs contain the bug fixes the original maintainer hasn't shipped yet. Genesis extracts them and adds them to your PITFALLS.md.

This is the feature that catches the issues that even the original repo authors haven't resolved.

---

4. Natural Language Architecture Choices (NLU Gate)

No more memorizing option letters.

Before:

Choose A, B, C, or D:
> B

Now:

Choose your architecture (A/B/C/D or describe in words):
> give me the scalable approach

I'll take that as B (scalable) - correct? [y/n]
> y

Genesis maps natural language to architecture choices using pattern matching. Say "I want the simple one", "let's go full production", "quick prototype" — it understands. Three failed attempts triggers a clean restart prompt, never a crash.

---

5. Zero-Friction Project Audits

genesis init now reads your project before it asks you anything.

If there's a pyproject.toml, package.json, go.mod, or README.md in the current directory, Genesis silently extracts the project name and description and uses them as the vision. No prompt. No interruption. It only asks if it finds nothing.

Run genesis init with no arguments inside an existing project and it figures out what you're building on its own.

---

6. Active Development Companion

After scaffolding, don't close the terminal — stay in it.

genesis companion

A new interactive mode that:

• Answers questions about your project using the vault + LLM
• Knows which project you're in (from pyproject.toml / README.md)
• Detects when you say "done", "exit", or start describing a completely different project
• Exits cleanly with a message pointing you to genesis init for the next one

Your scaffold is the starting line, not the finish line. Companion mode stays with you through the whole build.

---

🛡️ Stability and Resilience

GitHub Rate Limit Handling

Genesis now handles GitHub API limits gracefully. When the API returns 403 or 429:

1. Stops immediately — no partial run, no confusing error trace
2. Prints a clear message with the exact commands to fix it:

GitHub rate limit reached (60 requests/hour without a token).
To continue:
1. Go to https://github.com/settings/tokens/new
2. Select scope: public_repo
3. Run: genesis config set GITHUB_TOKEN <your-token>

No crash. No noise. Just instructions.

Test Suite: 316 Passing

Up from 307. Every new module ships with full coverage:

• test_github_rate_limit.py — 9 tests covering 403/429 detection, message content, fork analyzer propagation
• test_vault_and_resolve.py — 14 tests covering TTL, LRU eviction, stale fallback, stats
• test_new_features.py — 23 tests covering NLU gate, audit inference, companion exit detection

---

🧠 Under the Hood

Module	What it does
core/vault.py	LRU cache, 500 entries, 6-month TTL
core/resolve_engine.py	Vault-first SO lookup, stale warning
core/fork_analyzer.py	Top 3 forks by merged PRs (not stars)
core/nlu_gate.py	Natural language → A/B/C/D
core/audit_inference.py	Reads project files before prompting
core/companion.py	Exit detection, message routing
cli.py	Typer CLI wiring all modules together
config.py	API key management in ~/.genesis/config.json

---

⚡ How to Install

# Standalone (recommended for most users)
pip install genesis-architect
genesis config set LLM_API_KEY your-anthropic-or-openai-key
genesis init "describe what you want to build"

# Claude Code skill (original mode — still fully supported)
git clone https://github.com/maioio/genesis-architect ~/.claude/skills/genesis-architect

Optional — faster GitHub scanning:

genesis config set GITHUB_TOKEN your-github-token

Without a token you get 60 API requests/hour. With one: 5,000.

---

What's Next

• Demo GIF on the landing page
• PyPI publish (pip install genesis-architect from the public registry)
• Java and Ruby language templates (tracked in issues #17, #18)
• Show HN launch

---

316 tests. Zero regressions. Ships today.

v2.3.0 - 93 tests, CI overhaul, scaffold coverage

What's new in v2.3.0

Breaking changes

None. Drop-in upgrade.

Added

• 93 total unit tests (was 32): 41 for scaffold_generator, 52 for pitfall_coverage_check + genesis_subcommands
• SonarCloud coverage gate wired: coverage.xml now generated and passed to scanner on every PR
• Star history badge in README

Fixed

• CI failure rate cut: Gitleaks docker://gitleaks:latest (untagged, flaky) replaced with gitleaks-action@v2 (pinned)
• Sonarcloud + Snyk jobs skip gracefully when secrets missing - no wasted minutes for contributors/forks
• Duplicate pip install removed - CI ~40% faster
• sonar-project.properties: reportPaths was empty - SonarCloud was reporting 0% coverage on all PRs

Community

• Issue #14 closed: scaffold_generator now has full test coverage
• GitHub Discussions enabled
• README: social proof section added, demo GIF placeholder with recording guide

Install / upgrade

# Fresh install
git clone https://github.com/maioio/genesis-architect ~/.claude/skills/genesis-architect

# Upgrade existing
cd ~/.claude/skills/genesis-architect && git pull

No build step. Restart Claude Code to activate.

v2.2.0 - Community scripts, TOML source of truth, hardened validation

What's new in v2.2.0

5 new scripts closing community-requested issues

Issue #3 - Hard gate state files (genesis_state.py)
Phase 5 and Phase 6 gates are now machine-readable state files, not prose wishes.
Claude writes .genesis/phase-5-confirmed.json and .genesis/tests-passing.json before proceeding.

Issue #4 - Automated eval validation (eval_runner --mode validate)
Schema check on test_queries.json wired into CI. Catches eval drift before it ships.

Issue #5 - Single source of truth for folder structures (references/folder-structures.toml)
scaffold_generator.py now loads all 8 language/tier scaffold definitions from TOML. Removes 140-line hardcoded dict. Two sources can no longer drift.

Issue #6 - Mitigation coverage check (pitfall_coverage_check.py)
Mechanizes Phase 6 Step 6.5. Parses PITFALLS.md, walks src/, reports which mitigations are present in code and which are missing.

Issue #7 - genesis check command (genesis_subcommands.py)
Queries OSV.dev for CVEs against deps found in RESEARCH.md. Scans CI workflows for outdated action pins. JSON output with critical/warnings/info.

Security and robustness fixes

• scaffold_generator.py: path traversal via --name blocked with full input validation
• vault.py: atomic index write prevents partial corruption on crash
• drift_detector.py: baseline corruption recovery, bullet-list ADR parser, --help flag
• SonarCloud: 7 hotspots resolved with NOSONAR annotations on safe usages

Infrastructure

• Dependabot: all 4 GitHub Actions updated to latest major versions
• Branch protection: 5 required status checks on main
• 12 GitHub topics (was 8)

---

Install

# Claude Code
claude skills install maioio/genesis-architect

# Then use
genesis init "your project idea"

Full documentation: README

v1.1.0 - Development Companion Mode

What's new in v1.1.0

Added

• Phase 7 - Development Companion Mode: after scaffolding, stays active as a research partner throughout the project
• Language auto-detection: responds in the user's language (Hebrew, English, or any other)
• scripts/scaffold_generator.py: creates project structure for TypeScript, Python, Go, Rust
• scripts/research_validator.py: validates RESEARCH.md completeness
• scripts/eval_runner.py: measures trigger rate with 31 test cases
• evals/: 18 should-trigger + 13 should-not-trigger test queries
• examples/typescript-cli/: real output example with RESEARCH.md, PITFALLS.md, ROADMAP.md
• assets/: output templates for all three deliverable files
• plugin.json: manifest for skill marketplaces (agentskills.io spec)
• Go templates: Minimalist + Scalable boilerplate
• Rust templates: Minimalist + Scalable boilerplate
• YAML frontmatter in SKILL.md (agentskills.io compliant)

Changed

• SKILL.md rewritten to be language-agnostic
• Phase 2 research checkpoint improved
• README restructured with badges and install one-liner

Install

npx skills add https://github.com/maioio/genesis-architect

Usage

genesis init a REST API in TypeScript