# Zenith

An opinionated template for modern Python 3.12+ services, packages, and autonomous AI agents.

> [!NOTE]
>
> **What Zenith Is**: Zenith is a production-grade [Cookiecutter](<https://bwrob.dev/zenith/tools/cookiecutter/index.md>) project template for Python 3.12+. Rather than a runtime library you import, it scaffolds a complete, pre-configured repository with sub-second developer tooling and autonomous AI agent workflows—so you can write production code from commit zero without tooling debt.
>
> **Human-First, AI-Accelerated**: Zenith works identically as a pure human-driven developer workflow. All AI tooling and agent skills are 100% elective during scaffolding. The strict quality gates—100% test coverage, strict typing, complexity limits, and layer boundaries—help human developers just as much as AI agents by providing instant feedback, fearless refactoring, and zero review bikeshedding.

## Quick Start

> [!TIP]
>
> **Prerequisites &amp; First Steps** Zenith requires Astral **`uv`**. If you do not have `uv` installed yet:
>
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
>
> If terms like virtual environments, `uv`, or project scaffolding are unfamiliar, start with the [First Steps &amp; Core Concepts](<https://bwrob.dev/zenith/first-steps/index.md>) guide.

Scaffold a production-grade repository in seconds using `uvx`:

```console
$ uvx cookiecutter https://github.com/bwrob/zenith.git
$ cd my-awesome-service
$ uv sync
$ uv run poe test
100% test coverage reached (statements and branches).
$ uv run poe code-quality
All quality gates passed!
$ uv run poe docs-serve
Serving documentation at http://127.0.0.1:8000
```

## The Four Pillars

Zenith eliminates scaffolding debt and quality decay from commit zero across four foundational pillars:

- **[Modern Rust-Based Tooling](<https://bwrob.dev/zenith/tools/index.md>)**

  ---

  Sub-second developer loops powered by **[uv](<https://bwrob.dev/zenith/tools/uv/index.md>)**, **[Ruff](<https://bwrob.dev/zenith/tools/ruff/index.md>)**, **[Pyrefly](<https://bwrob.dev/zenith/tools/pyrefly/index.md>)**, **[Tach](<https://bwrob.dev/zenith/tools/tach/index.md>)**, **[Deptry](<https://bwrob.dev/zenith/tools/deptry/index.md>)**, **[complexipy](<https://bwrob.dev/zenith/tools/complexipy/index.md>)**, and **[Zensical](<https://bwrob.dev/zenith/tools/zensical/index.md>)**. All tasks run through **[Poe the Poet](<https://bwrob.dev/zenith/tools/poethepoet/index.md>)** for identical local and CI execution.
- **[First-Class AI Agent Readiness](<https://bwrob.dev/zenith/skills/index.md>)**

  ---

  Built for autonomous pair-programming when desired, yet completely elective. Scaffold all assistants, select your preferred tools, or exclude AI configs entirely for a traditional Python repository. Audited in the [Agentic Tool Matrix](<https://bwrob.dev/zenith/skills/#agentic-tool-compatibility-matrix>).
- **[Automated Quality Guardrails](<https://bwrob.dev/zenith/philosophy/index.md>)**

  ---

  Rigor that accelerates humans and agents alike: **100% mandatory test coverage** (`fail_under = 100`), strict static typing with Pyrefly, cognitive complexity limits (\<= 10), module boundary enforcement, and CI security auditing.
- **[Hermetic Delivery &amp; CI/CD](<https://bwrob.dev/zenith/ci-actions/index.md>)**

  ---

  Zero-drift automation: multi-version matrix testing across Python 3.12–3.15, isolated wheel package smoke tests, automated documentation publishing, and PyPI Trusted Publishing with supply-chain safeguards.

## Architecture at a Glance

Scaffolded projects enforce strict separation between domain logic, public interfaces, and automated quality guardrails:

```bash
📁 my-awesome-service/
├── 📁 src/my_awesome_service/     # Core package source, public API, and optional Typer CLI
├── 📁 tests/                      # Comprehensive test suite with 100% coverage gate
├── 📁 docs/                       # Zensical documentation site with live preview
├── 📁 .agents/skills/             # Modular agent skills (workflows, tools, style guides)
├──  pyproject.toml              # Dependencies and packaging standards (PEP 621)
├──  poe_tasks.toml              # Hermetic task runner commands (Poe the Poet)
└──  AGENTS.md                   # Canonical AI agent instructions and boundary rules
```

### Production-Grade Code by Default

Every generated repository produces strictly typed, immutable, and fully tested Python out of the box:

```python
"""Core domain logic with strict typing and immutability."""

from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class Greeter:
    """Greeting domain entity."""

    recipient: str

    def format(self) -> str:
        """Format greeting with recipient."""
        return f"Hello, {self.recipient}!"
```

```python
"""Command line interface powered by Typer and Rich."""

from typing import Annotated

import typer
from my_awesome_service.core import Greeter
from rich.console import Console

app = typer.Typer(no_args_is_help=True)
console = Console()


@app.command()
def greet(
    name: Annotated[str, typer.Argument(help="Name to greet.")] = "World",
) -> None:
    """Display a personalized greeting."""
    greeter = Greeter(recipient=name)
    console.print(f"[bold green]✨ {greeter.format()}[/bold green]")
```

```python
"""Automated CLI test suite with 100% coverage gate."""

from my_awesome_service.cli import app
from typer.testing import CliRunner

runner = CliRunner()


def test_greet() -> None:
    result = runner.invoke(app, ["greet", "Zenith"])
    assert result.exit_code == 0
    assert "✨ Hello, Zenith!" in result.stdout
```

> [!TIP]
>
> **Explore the Live Showcase Repository**
>
> Browse instantiated code, commit history, and GitHub Actions runs in **[bwrob/zenith-example on GitHub](<https://github.com/bwrob/zenith-example>)**. For release notes and version history, see the **[Changelog](<https://bwrob.dev/zenith/changelog/index.md>)**.