claude-code-generator 0.1.0__py3-none-any.whl

claude_code_generator-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: claude-code-generator
+Version: 0.1.0
+Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
+Author: Silvio Baratto
+License: MIT
+Project-URL: Homepage, https://github.com/SilvioBaratto/code-generator
+Project-URL: Repository, https://github.com/SilvioBaratto/code-generator
+Project-URL: Issues, https://github.com/SilvioBaratto/code-generator/issues
+Keywords: claude,claude-code,code-generation,llm,cli,orchestrator
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: claude-agent-sdk
+Requires-Dist: typer
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# code-generator
+
+A Python CLI that orchestrates Claude Code end-to-end to generate a whole project from a `requirements.md` file. Three commands — `init`, `generate`, `review` — plus `status`. Works for any project type: Python CLI, FastAPI, Angular, NestJS, full-stack, finance, BAML/LLM.
+
+> **Max subscription only.** This tool uses **exclusively** the Claude Max subscription. It strips every environment variable that could route a call through the API and aborts on startup if any are still present. There is no path to API credit billing — see [Safety constraints](#safety-constraints) below.
+
+## Install
+
+```bash
+pipx install code-generator        # recommended
+# or
+pip install code-generator          # user-site
+# or, from source
+git clone git@github.com:SilvioBaratto/code-generator.git
+cd code-generator && pip install -e ".[dev]"
+```
+
+## Authentication
+
+```bash
+# Claude Code (Max subscription)
+claude auth login
+
+# GitHub (SSH protocol)
+gh auth login -h github.com -p ssh
+gh config set git_protocol ssh
+```
+
+## Commands
+
+### `code-generator init [--template TYPE] [--force]`
+
+Scaffold `.code-generator/` in the current directory with a ready-to-fill `requirements.md`. Templates: `fastapi`, `angular`, `nestjs`, `fullstack`, `python-cli`, `finance`. Refuses to clobber an existing `.code-generator/` without `--force`.
+
+```bash
+code-generator init --template fastapi
+$EDITOR .code-generator/requirements.md
+```
+
+### `code-generator generate [flags]`
+
+Read `.code-generator/requirements.md` and orchestrate Claude Code through the 0→7 phase pipeline:
+
+| Phase | Action | Model |
+|---|---|---|
+| 0 | Complexity analysis (single vs multi-cycle) | Opus 4.6 |
+| 1 | Planning — creates GitHub issues + milestone | Opus 4.6 |
+| 2 | Per-issue review | Opus 4.6 |
+| 3-4 | Implementation, fresh SDK session per issue (TDD) | Sonnet 4.6 |
+| 5 | Closure + cross-module review | Opus 4.6 |
+| 6 | Test suite, max 3 retries on failure | Sonnet 4.6 |
+| 7 | Commit message + git add/commit/push | Haiku 4.5 |
+
+Flags:
+
+| Flag | Description | Default |
+|---|---|---|
+| `--dry-run` | Run only Phase 0 + Phase 1 (planning) | false |
+| `--phase N` | Resume from phase N | — |
+| `--continue` | Resume from the last completed phase (reads `state.json`) | false |
+| `--mode auto\|single\|multi-cycle` | Force a mode (default `auto` runs Phase 0 first) | auto |
+| `--cycle N` | Resume from cycle N (multi-cycle only) | — |
+
+In multi-cycle mode each cycle is a GitHub Milestone and produces a committable, working increment. Each cycle starts a fresh SDK session and re-reads the committed codebase, so the model never relies on stale conversational context.
+
+If the Max subscription hits a rate limit, the tool **pauses** — it persists the session id and `paused_until` timestamp atomically to `.code-generator/state.json`, sleeps until the window resets, and resumes with `--resume <session_id>`. A killed process will resume on its own when re-run.
+
+### `code-generator review [--create-issues] [--severity LEVEL]`
+
+Run a standalone Opus 4.6 review of the current codebase against the design principles in `requirements.md` §4 (SOLID, Clean Code, TDD, YAGNI/KISS/DRY). With `--create-issues`, every finding becomes a GitHub Issue.
+
+### `code-generator status`
+
+Print a Rich table with the current mode, current cycle, current phase, open/closed issue counts, the rate-limit pause state (with minutes remaining if paused), and the last error.
+
+## Safety constraints
+
+The tool enforces eight non-negotiables (see `CLAUDE.md` for the full list):
+
+1. **Max subscription only, zero API credits.** Before any SDK or subprocess call, the tool strips `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BEDROCK_API_KEY`, `ANTHROPIC_VERTEX_PROJECT_ID`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX` from the environment. A startup check refuses to run if any are present.
+2. **Never `--bare`.** The CLI flag `--bare` skips OAuth and forces API credits — it is **never** passed by this tool. If Anthropic ever makes `--bare` the default for `claude -p`, pin the CLI version or pass the opposite flag explicitly.
+3. **YOLO mode always.** Every SDK call uses `permission_mode="bypassPermissions"`; the subprocess fallback uses `--dangerously-skip-permissions`.
+4. **Overage protection.** On every `RateLimitEvent`, the tool checks `info.overage_status` and aborts immediately if it is anything other than `None` or `"disabled"`. Reference incident: [anthropics/claude-code#37686](https://github.com/anthropics/claude-code/issues/37686) — a user burned $1,800 in two days because billing overage was silently enabled.
+5. **Wait-and-resume rate-limit handling.** Rate limits are not retried with exponential backoff — the tool sleeps until `resets_at + 60s` and resumes the same session. Backoff (10→20→40→80→120s) only applies to non-rate-limit transient errors.
+6. **Fresh SDK session per issue.** The implementation phase never reuses conversational context across issues — each issue is a `/clear`-equivalent fresh session.
+7. **Atomic state writes.** `.code-generator/state.json` is updated via `tmp → os.replace(tmp, STATE)` so a crash mid-write cannot corrupt it.
+8. **Fixed model per phase.** Opus 4.6 for phases 0/1/2/5; Sonnet 4.6 for phases 3/4/6; Haiku 4.5 for phase 7's commit message.
+
+## Troubleshooting
+
+**Startup fails with "dangerous environment variables present".** A previous shell session exported `ANTHROPIC_API_KEY` (or another billing-routing variable). `unset` it and try again — the tool is intentionally strict so a stray export never costs you money.
+
+**Rate limit reached.** Run `code-generator status` to see how many minutes remain on the current pause. The next `code-generator generate --continue` will wait out the rest of the window and resume the same session automatically.
+
+**`gh issue create` fails.** Confirm `gh auth status` reports an authenticated SSH session for `github.com`, and that the current directory is inside a repo with a default remote configured.
+
+**Tests don't pass after Phase 6.** The orchestrator skips Phase 7 (commit) when the test runner reports persistent failures. Fix the failing tests manually, then run `code-generator generate --continue` to re-enter from where it stopped.
+
+## Project layout
+
+```
+src/code_generator/
+├── cli.py                # Typer entry point: init, generate, review, status
+├── env.py                # DANGEROUS_VARS, build_agent_env, assert_safe_environment
+├── state.py              # State dataclasses + atomic load/save
+├── prompts/              # Packaged prompt-phase-*.md files + load_prompt
+├── templates/            # Project templates for `init`
+├── logging_setup.py      # Per-phase log files under .code-generator/logs/
+├── gh.py                 # Subprocess wrapper for issues, milestones, labels
+├── agents.py             # Tech-stack detector + agent selection matrix
+├── runner/
+│   ├── sdk_runner.py     # claude-agent-sdk wrapper, RateLimitEvent handling
+│   ├── subprocess_runner.py  # CLI fallback, stream-json parser
+│   ├── rate_limit.py     # Wait-and-resume main loop
+│   └── retry.py          # Backoff + circuit breaker
+├── orchestrator/
+│   ├── phase0_complexity.py  # single vs multi-cycle decision
+│   ├── phase1_plan.py        # milestone + issues
+│   ├── phase2_review.py      # per-issue review
+│   ├── phase3_4_implement.py # TDD loop, fresh session per issue
+│   ├── phase5_closure.py     # closure + fix-issue feedback loop
+│   ├── phase6_test.py        # test runner, max 3 retries
+│   ├── phase7_commit.py      # Haiku commit message + push with rebase retry
+│   └── cycle_loop.py         # multi-cycle driver
+└── commands/             # init, status, generate, review (Typer commands)
+```
+
+## Development
+
+```bash
+git clone git@github.com:SilvioBaratto/code-generator.git
+cd code-generator
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q
+ruff check src tests
+```
+
+## Reference
+
+The full specification lives in [`requirements.md`](requirements.md). Each prompt file (`prompt-phase-*.md`, `prompt-review.md`) is loaded verbatim by the orchestrator with `{NAME}` placeholders substituted at runtime — edit the prompts there, not inline in Python.
+
+## License
+
+MIT.

claude_code_generator-0.1.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+claude_code_generator-0.1.0.dist-info/licenses/LICENSE,sha256=Pmk91Ef-CmCxp3mvYU1DWeLRGKEC3HFitMjivm45BIY,1071
+code_generator/__init__.py,sha256=_ZMXTePzmM8wjXWqBXJ1w9EezQ3zEOZhdbwAC1qiCfc,97
+code_generator/agents.py,sha256=6D-BORzWkHYs2V4O0Z4RK8Hwsgkn5zqD-ZyWBKuOjX0,5251
+code_generator/cli.py,sha256=JMU7wVpztnavkTkoGXrvEmMqOuEuwaxa-WH-wuWrANk,1244
+code_generator/env.py,sha256=e-wsII0H7IB0rwJB4SlqmpfSG6asqBLA7rpjCU2fpBQ,1760
+code_generator/gh.py,sha256=Iw3mIPNZ6l8gqLUMjwbAcR9bD_EKLz7im1ajpAniYsY,8951
+code_generator/logging_setup.py,sha256=pu5c8I4BrFlSU80QMDVUVKf67q_UwGtQRe8hYI975fc,2295
+code_generator/state.py,sha256=O_qd7eSMpd2J9KtkHobDC6VICCjyViSW5K32DGSwYHU,5220
+code_generator/commands/__init__.py,sha256=UgM_pau4ln3VOxO6p3ElNrFF_kGxpNNYGlw04FHt1ho,64
+code_generator/commands/generate.py,sha256=2TP6X94gmBNrZURzDwIftA6PoGq2PDfgYCyGgl9ax7c,7611
+code_generator/commands/init.py,sha256=9faehMIm_5F4MytOcej0JjFzduVhz-oVc3bb1_-1_Nk,2110
+code_generator/commands/review.py,sha256=U0c_xiMLHYgfVwiPTOGXgyvNDWj7m0y1xO5JImuI7UY,3434
+code_generator/commands/status.py,sha256=T7-kf9EsrP9zOOGrR_9BqnE036J9px3mRabZ6LJxzr0,2566
+code_generator/orchestrator/__init__.py,sha256=B_bjMB96SZPeNAJ07DSNY25c8UDMz_eqqsel-QtU_C4,129
+code_generator/orchestrator/cycle_loop.py,sha256=LbM7mrRWAL2OWLe0WbaFa2c4tsAWs2uNaVONj9Tws7s,12971
+code_generator/orchestrator/phase0_complexity.py,sha256=D0reZQMQJqGg1V7kNEA52TUZ497gcOMh0FCVAWYyd5o,4983
+code_generator/orchestrator/phase1_plan.py,sha256=ZwqwlHf10Ay6wvAnwRTI6lqQAhkSF2biBoKVDLvGMWs,5433
+code_generator/orchestrator/phase2_review.py,sha256=_OGWi11pzt9AHSvYk0uBjeWt52C3KRyZI0eUI3-S1Pw,3937
+code_generator/orchestrator/phase3_4_implement.py,sha256=iLoOdq9bMbRe9st2BZnk6LESsyGJKTeYpcmB6vW9mC8,5523
+code_generator/orchestrator/phase5_closure.py,sha256=Ak6RSVRop5b4D8NWqeBZ06y5DZRQHAOMYtax9kMC2fE,4841
+code_generator/orchestrator/phase6_test.py,sha256=3leV1K3vGP9arfretKPZg4d-ApWIDR5s_TNMvR5f-1U,2924
+code_generator/orchestrator/phase7_commit.py,sha256=HzZt40s-W9vbaolmpo7mAXWE624ei1tByM_7bnKNQ3k,5052
+code_generator/prompts/__init__.py,sha256=uME1HtGcZQuGahcCRdoN2CmVBk7SIfS6U1PdIYJN_ZY,3118
+code_generator/prompts/prompt-phase-0-complexity.md,sha256=ffZMcqJMeXPUjKVTfLVM_Pj_NF7ofEVf6fa9SWAJp2A,4290
+code_generator/prompts/prompt-phase-1-planning.md,sha256=aRILIz162x10TXsk2Zk4-apbbJBgdkizibvI2iX41OE,11523
+code_generator/prompts/prompt-phase-2-issue-review.md,sha256=xvn1VSzV19mgEZrZG5D2V-1HUfDv9ZTjFf_BOiQCqcE,3400
+code_generator/prompts/prompt-phase-3-implementation.md,sha256=FEqH6b5k-jZblYt2ydAIdigoipsBxX63ExkgrxC_moE,10955
+code_generator/prompts/prompt-phase-5-final-review.md,sha256=kU8Mb3YfiK5c07G5MEoHfNZu68C9697Uv5lqZZMAs7A,6047
+code_generator/prompts/prompt-phase-6-test.md,sha256=8St1Z_b5A38oZkd2Zq8OZRmHZ_tFyW1AgCbRbd3ciC8,4799
+code_generator/prompts/prompt-phase-7-commit.md,sha256=yx7d-DaJgoyYYcpf3gnUIvcXoZQBch-BMdyHY_zB9-c,3057
+code_generator/prompts/prompt-review.md,sha256=KP3c2QpLNpv4RvIuMVJAL-YU-JZkJ9MvcY3C1HHCuLM,4441
+code_generator/runner/__init__.py,sha256=kZ5vJ0DfHOVufBgni7_bxKfHOeu6npx7XGDTOpP1-Nc,662
+code_generator/runner/rate_limit.py,sha256=7oKuRMEkRrjp-rXFxxn7Fj5hNqdv9tHkMPOHElDYCZ8,3882
+code_generator/runner/retry.py,sha256=j4O9uRhm_DMsd1O0eyJyuWqOIc-_uFL0HyV1-_qkIZo,5621
+code_generator/runner/sdk_runner.py,sha256=5pgmiENy_nee2VMivGnRlEBUUsSjndVJuTmXWfFw6NU,9353
+code_generator/runner/subprocess_runner.py,sha256=E3LK_jLT50qwBVh5NDWubqN_neA13zphBTB2HNjYxJU,6571
+code_generator/templates/__init__.py,sha256=HbGi1Gw9KI0QWKlYT-PGPVcQF4YfQzE35V07F7BIOlM,48
+code_generator/templates/angular.md,sha256=ey8aQJSaWPKNhue-ZOIzZygpOw3udRVFTThxE21doG4,306
+code_generator/templates/base.md,sha256=CsliWXVVHGg_HfK0Ls2F6zocYAsHQPt4uVPRPkzekF4,792
+code_generator/templates/fastapi.md,sha256=N1loHS9IWGOmvMA2Op-EY1Ys4Igpt2sxsIei0YV3qa0,304
+code_generator/templates/finance.md,sha256=sqfS0HQJB05sSsWACtj5JPDm2GGNxd3yEOw9G3y7faE,222
+code_generator/templates/fullstack.md,sha256=ub6pfQU2Cz9x29BJExgxMKb_c-9ev4briEzI0fYON8g,610
+code_generator/templates/nestjs.md,sha256=-ENYbwCOScFJ-9Tvl8R0QEfLDe9bj7YLgoW_HIHVKhc,182
+code_generator/templates/python-cli.md,sha256=g6pcznCbc1f11LeKuEnGu74YHM-qCgtYlza9j5QuukU,200
+claude_code_generator-0.1.0.dist-info/METADATA,sha256=1Dzr76VnIWs9C0tbnGQ8BTvexodWdFhI_GLidoDBTJ8,9673
+claude_code_generator-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+claude_code_generator-0.1.0.dist-info/entry_points.txt,sha256=Tg2EXnr2LvXDTR5_9ArK5HUyUCzLIycIjNbx3I2lmw4,58
+claude_code_generator-0.1.0.dist-info/top_level.txt,sha256=FYLzn8l0Cgl2tARhLjBAQNS3manGG-zM_rd_1v7C8HQ,15
+claude_code_generator-0.1.0.dist-info/RECORD,,

claude_code_generator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

claude_code_generator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+code-generator = code_generator.cli:app

claude_code_generator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silvio Baratto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_code_generator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+code_generator

code_generator/__init__.py

@@ -0,0 +1,3 @@
+"""code-generator: orchestrator CLI for end-to-end project generation."""
+
+__version__ = "0.1.0"

code_generator/agents.py

@@ -0,0 +1,177 @@
+"""Tech-stack detector and agent selection matrix (requirements.md §7).
+
+Parses the ``## Tech Stack`` section of a requirements file and returns
+an :class:`AgentSelection` dataclass describing which agents and skills
+to activate for the project.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AgentSelection:
+    """Immutable record of chosen agents and skills for a project.
+
+    Attributes:
+        primary: Tuple of primary agent names to assign as implementers.
+        support: Tuple of support/advisory agent names.
+        skills: Tuple of skill names to auto-load.
+    """
+
+    primary: tuple[str, ...]
+    support: tuple[str, ...]
+    skills: tuple[str, ...]
+
+
+# ---------------------------------------------------------------------------
+# Fallback / defaults
+# ---------------------------------------------------------------------------
+
+_GENERIC_FALLBACK = AgentSelection(
+    primary=("python-pro",),
+    support=(),
+    skills=("solid-principles",),
+)
+
+# ---------------------------------------------------------------------------
+# Matrix definitions — ordered from most-specific to least-specific
+# ---------------------------------------------------------------------------
+
+_ANGULAR_FASTAPI = AgentSelection(
+    primary=("frontend-developer", "python-pro", "fastapi-expert-agent"),
+    support=("typescript-pro", "tailwind-patterns", "ui-ux-designer", "supabase-connection-expert"),
+    skills=("solid-principles", "python-expert"),
+)
+
+_ANGULAR_NESTJS = AgentSelection(
+    primary=("frontend-developer", "nestjs-expert"),
+    support=("typescript-pro", "tailwind-patterns", "ui-ux-designer", "supabase-connection-expert"),
+    skills=("solid-principles",),
+)
+
+_ANGULAR_ONLY = AgentSelection(
+    primary=("frontend-developer",),
+    support=("typescript-pro", "tailwind-patterns", "ui-ux-designer"),
+    skills=("solid-principles",),
+)
+
+_FASTAPI = AgentSelection(
+    primary=("python-pro", "fastapi-expert-agent"),
+    support=("supabase-connection-expert",),
+    skills=("solid-principles", "python-expert"),
+)
+
+_NESTJS = AgentSelection(
+    primary=("nestjs-expert",),
+    support=("supabase-connection-expert",),
+    skills=("solid-principles",),
+)
+
+_PORTFOLIO = AgentSelection(
+    primary=("riskfolio-expert", "python-pro"),
+    support=(),
+    skills=("skfolio", "yfinance"),
+)
+
+_BAML = AgentSelection(
+    primary=("baml-expert-agent", "python-pro"),
+    support=(),
+    skills=("solid-principles",),
+)
+
+_PYTHON_CLI = AgentSelection(
+    primary=("python-pro",),
+    support=(),
+    skills=("solid-principles", "python-expert"),
+)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def _extract_tech_stack_block(text: str) -> str:
+    """Return the text between ``## Tech Stack`` and the next ``## `` heading.
+
+    Args:
+        text: Full content of a requirements file.
+
+    Returns:
+        Lowercased content of the Tech Stack section, or an empty string
+        when the section is absent.
+    """
+    marker = "## tech stack"
+    lower = text.lower()
+    start = lower.find(marker)
+    if start == -1:
+        return ""
+
+    block_start = start + len(marker)
+    # Find the next level-2 heading after the marker.
+    next_heading = lower.find("\n## ", block_start)
+    block = lower[block_start:] if next_heading == -1 else lower[block_start:next_heading]
+
+    return block
+
+
+def detect(requirements_path: Path) -> AgentSelection:
+    """Parse a requirements file and return the matching AgentSelection.
+
+    Detection follows the §7 matrix in requirements.md.  Full-stack
+    combos are checked before single-stack patterns.  Falls back to the
+    generic ``python-pro`` + ``solid-principles`` selection when the file
+    is missing or no keyword matches.
+
+    Args:
+        requirements_path: Path to a ``requirements.md`` file (need not exist).
+
+    Returns:
+        The most-specific :class:`AgentSelection` that matches the stack,
+        or the generic fallback when no match is found.
+    """
+    if not requirements_path.exists():
+        return _GENERIC_FALLBACK
+
+    text = requirements_path.read_text(encoding="utf-8")
+    block = _extract_tech_stack_block(text)
+
+    if not block:
+        return _GENERIC_FALLBACK
+
+    has_angular = "angular" in block or " ng " in block or " ng," in block
+    has_fastapi = "fastapi" in block or "python api" in block
+    has_nestjs = "nestjs" in block or "nest" in block
+
+    # Full-stack combos checked first (most specific).
+    if has_angular and has_fastapi:
+        return _ANGULAR_FASTAPI
+
+    if has_angular and has_nestjs:
+        return _ANGULAR_NESTJS
+
+    if has_angular:
+        return _ANGULAR_ONLY
+
+    if has_fastapi:
+        return _FASTAPI
+
+    if has_nestjs:
+        return _NESTJS
+
+    if "portfolio" in block or "riskfolio" in block or "skfolio" in block:
+        return _PORTFOLIO
+
+    if "baml" in block or "llm function" in block:
+        return _BAML
+
+    if "typer" in block or "click" in block or "python cli" in block:
+        return _PYTHON_CLI
+
+    return _GENERIC_FALLBACK

code_generator/cli.py

@@ -0,0 +1,49 @@
+"""Entry-point CLI for code-generator.
+
+Exposes a Typer application with --version and subcommands:
+init, status, generate, review.
+"""
+
+from typing import Annotated
+
+import typer
+
+import code_generator
+from code_generator.commands.generate import generate_command
+from code_generator.commands.init import init_command
+from code_generator.commands.review import review_command
+from code_generator.commands.status import status_command
+
+app = typer.Typer(
+    name="code-generator",
+    help="Orchestrate Claude Code to generate whole projects from a requirements.md.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"code-generator {code_generator.__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """code-generator CLI root."""
+
+
+app.command(name="init")(init_command)
+app.command(name="status")(status_command)
+app.command(name="generate")(generate_command)
+app.command(name="review")(review_command)

code_generator/commands/__init__.py

@@ -0,0 +1 @@
+"""Typer command implementations, one module per subcommand."""