🚀 GENESIS — AI-Driven Venture Studio

Genesis is a production-grade, highly disciplined, spec-driven development workspace and preproduction engine. It automates product discovery, ideation validation, Web-scale competitive intelligence, and adversarial auditing to draft comprehensive, publication-grade Venture Specification Papers (fully formatted with LaTeX equations, tabular pricing matrices, and ASCII diagrams).

This repository transitions AI-assisted software development from unstructured "vibe-coding" to a rigorous pipeline combining Spec-Driven Development (SDD) and Test-Driven Agentic Development (TDAD).

---

🛠️ Key Architectural Innovations

1. Asymmetric Human-in-the-Loop State Router

To resolve Streamlit's notorious re-run and React hydration/unmount freezes, the interface executes an asymmetric, non-blocking Multi-Stage State Graph governed by explicit session states (init ➔ scoping ➔ planning ➔ running ➔ completed).

• Scoping Stage: Generates 2 highly targeted technical scoping questions to calibrate the engine before searching.
• Planning Stage: Formulates a tailored plan (3 queries and a 6-section outline) and displays them in editable inputs, allowing the user to refine or add custom directions before spending API tokens.
• Execution Stage: Locks the inputs and executes the pipeline autonomously to completion, ensuring zero UI locks or connection drops.

2. Self-Optimizing Model Router & Dynamic Cache

The underlying query loop implements an adaptive, session-aware caching layer across all agents (researcher.py, triz_innovator.py, red_team.py):

• Skip-on-First: If a free Google AI Studio key is used, it skips known-unsupported models (gemini-3.1-pro 404 and gemini-2.5-pro 429) instantly, saving ~15 seconds of error loops on first run.
• Model Blacklist: Models returning 404s are appended to a class-level set and never attempted again during the session.
• Successful Model Cache: When a model succeeds (like gemini-3.5-flash), it is cached. All subsequent requests prioritize this model first, reducing overall pipeline latency by ~90% (saving 15s of connection loops per section).
• Smart Delay Parser: If a 429 occurs, it parses the RPC delay. If the wait is long, it immediately fails over to the next candidate model in the chain instead of sleeping.

3. Dual-Pass Web Crawling & Gap Analysis

• Scraper (Pass 1 - Breadth): Scrapes crawled pages up to 40,000 characters per page. It parses and retains Markdown-like headers, bullet lists, and tables intact, ensuring pricing and matrix grids are preserved.
• VC Gap Analysis: Simulates a cynical Cryptographic VC Auditor persona to review Pass 1 data, identify missing assumptions or equations, and run 2 targeted depth queries (Pass 2) to fill missing facts.

4. Section-by-Section Draft Compiler

To completely bypass the standard 8,192 output token limit (which forces single-pass models to condense or truncate reports), Genesis compiles each of the 6 sections in individual high-context API calls. This enables the model to write 1,000+ words per section, resulting in massive, publication-grade 15-page specifications.

---

📂 Project Architecture

claude-dev-shop/
├── CLAUDE.md              # Global workflows, TDAD guidelines, and quality gates
├── MEMORY.md              # Index of local file-based persistent memories
├── PLAN.md                # Design specifications for self-optimizing retry loops
├── .gitignore             # Safeguards secrets (.env) and excludes swap files
├── preproduction/         # 🚀 The Discovery & Preproduction WebUI
│   ├── app.py             # Streamlit Entry point (asymmetric HIL stage-router)
│   ├── requirements.txt   # WebUI & SDK dependencies (google-genai, bs4, httpx)
│   ├── proposals/         # Permanent archive of generated specs (<slug>-proposal.md)
│   └── agents/            # Specialized Modular Agents
│       ├── triz_innovator.py   # TRIZ contradiction resolver & cryptographer
│       ├── researcher.py       # Dual-pass search, scraper, and sectional compiler
│       └── red_team.py         # VC Skeptics Panel (Tech, Market, and Financial)
└── specs/                 # Document specifications and EARS-syntax templates

---

🚀 Installation & Local Run

1. Configure Credentials

Create a .env file in your project root and add your Google AI Studio key:

GEMINI_API_KEY=your_google_ai_studio_api_key_here

(Optional: If no API key is found, the system will fallback securely to GCP Application Default Credentials / Vertex AI using your project configurations)

2. Install Dependencies

pip install -r preproduction/requirements.txt

3. Launch the Application

Run the Streamlit application:

streamlit run preproduction/app.py

Open http://localhost:8501 in your browser.

---

📦 Installed Skill Suite (Ponytail Suite)

This workspace is pre-integrated with the Ponytail code-quality and audit suite:

• ponytail — Runs general code structure and dependency graph sweeps.
• ponytail-review — Automated code quality and best-practice reviews.
• ponytail-audit — Full codebase security auditing (scans for credentials and path leaks).
• ponytail-debt — Scans and quantifies refactoring paths and technical debt.

To execute any of these tools on your local workspace:

/ponytail-debt

---

👥 Authors

• AndyTheGuy (Lead Venture Architect)
• Claude (AI Co-Author & Lead Engineer)