ai-doc-gen / rules

---
description: Core project architecture, patterns, and conventions for the AI Documentation Generator
alwaysApply: true
---

# AI Documentation Generator — Project Overview

Multi-agent Python 3.13 CLI tool (`ai-doc-gen`) that analyzes codebases with concurrent AI agents and generates documentation: `.ai/docs/*.md` analyses, README.md, and AI assistant config files (CLAUDE.md, AGENTS.md, .cursor/rules/).

## Layout

- `src/main.py` — CLI entry point; commands: `analyze`, `generate readme`, `generate ai-rules`, `cronjob analyze`. CLI arguments are generated dynamically from Pydantic config models.
- `src/config.py` — module-level constants from env vars; `ANALYZER_LLM_*` and `DOCUMENTER_LLM_*` are required at import time, `AI_RULES_LLM_*` falls back to documenter values.
- `src/handlers/` — one handler per command (`analyze.py`, `readme.py`, `ai_rules.py`, `cronjob.py`), all implement `AbstractHandler.handle()` from @src/handlers/base_handler.py.
- `src/agents/` — pydantic-ai agents (`analyzer.py`, `documenter.py`, `ai_rules_generator.py`), Jinja2 prompt templates in `prompts/*.yaml`, tools in `tools/`.
- `src/utils/` — `logger.py` (singleton `Logger`, call `init()` before use), `prompt_manager.py`, `retry_client.py`, `worker_pool.py`, `repo.py`, `dict.py`.
- `skills/` + `.claude-plugin/` — Claude Code skills mirroring the agents; keep in sync when changing agent prompts.

## Core patterns

- **Handler pattern**: handler configs multiple-inherit `BaseHandlerConfig` + agent config, e.g. `class AnalyzeHandlerConfig(BaseHandlerConfig, AnalyzerAgentConfig)`.
- **Concurrency**: 5 analysis agents run through `WorkerPool` (semaphore-bounded; `ANALYZER_MAX_WORKERS`, 0 = CPU count); AI-rules generators use `asyncio.gather(return_exceptions=True)`.
- **Error isolation**: an agent failure is logged and skipped; fail the run only when ALL agents fail (raise `ValueError`).
- **Configuration precedence**: Pydantic defaults < `.ai/config.yaml` < CLI arguments, merged via `merge_dicts()`.
- **LLM access**: OpenAI-compatible only — `OpenAIChatModel` + `OpenAIProvider` with configurable base URL, wrapped in a retrying HTTP client. Temperature 0.0 everywhere.

## Commands

```bash
uv sync                                            # install (Python 3.13, <3.14)
uv run src/main.py analyze --repo-path .           # write .ai/docs/*.md
uv run src/main.py generate readme --repo-path .
uv run src/main.py generate ai-rules --repo-path .
uv run ruff format src/ && uv run ruff check src/  # before every PR
```

## Output locations

- Analyses: `{repo}/.ai/docs/*.md` — README: `{repo}/README.md` — AI rules: `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`
- Logs: `.logs/{repo_name}/{YYYY_MM_DD}/{timestamp}.log` (file INFO, console WARNING)

## Git conventions

- Branches: `main`, `feature/*`, `fix/*`, `ai-analysis-YYYY-MM-DD` (automated)
- Commits: `[Category] Brief description` — `[Feature]`, `[Fix]`, `[Refactor]`, `[Docs]`, `[Config]`, `[AI]`
- PRs squash-merge to `main`. No automated tests — verify by running the CLI against a test repo.