claude-code-generator 0.1.0__tar.gz

claude_code_generator-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,145 @@
+# 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/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-code-generator"
+version = "0.1.0"
+description = "Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Silvio Baratto" }]
+keywords = ["claude", "claude-code", "code-generation", "llm", "cli", "orchestrator"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "claude-agent-sdk",
+    "typer",
+    "rich",
+]
+
+[project.urls]
+Homepage = "https://github.com/SilvioBaratto/code-generator"
+Repository = "https://github.com/SilvioBaratto/code-generator"
+Issues = "https://github.com/SilvioBaratto/code-generator/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "ruff",
+]
+
+[project.scripts]
+code-generator = "code_generator.cli:app"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+code_generator = [
+    "prompts/*.md",
+    "templates/*.md",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "TCH"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["E501", "SIM117", "TC003"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

claude_code_generator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_code_generator-0.1.0/src/claude_code_generator.egg-info/PKG-INFO

@@ -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.