From zero to hero — production-ready Python, without the ceremony.

git clone https://github.com/nullhack/python-project-template
cd python-project-template
curl -LsSf https://astral.sh/uv/install.sh | sh  # skip if uv installed
uv sync --all-extras
opencode && @setup-project                        # personalise for your project
uv run task test && uv run task lint && uv run task static-check

Most Python templates give you a folder structure and a Makefile. This one gives you a complete delivery system: five AI agents, a structured five-step workflow, and quality gates that cannot be silenced by convention.

The goal is to give every project — from its first commit — the same rigour that mature teams take years to establish.

• No feature starts without written acceptance criteria — Gherkin Example: blocks traced to tests
• No feature ships without adversarial review — the reviewer's default hypothesis is "broken"
• No guesswork on test stubs — generated automatically from .feature files
• No manual @id tags — assigned automatically when you run tests
• AI agents for every role — each agent has scoped instructions and cannot exceed its authority

SCOPE → ARCH → TDD LOOP → VERIFY → ACCEPT

WIP limit: 1 feature at a time. Features are .feature files that move through folders:

docs/features/backlog/      ← waiting
docs/features/in-progress/  ← building (max 1)
docs/features/completed/    ← shipped

uv run task test          # Full suite + coverage
uv run task test-fast     # Fast, no coverage (use during TDD loop)
uv run task lint          # ruff check + format
uv run task static-check  # pyright
uv run task run           # Run the app

Write acceptance criteria in Gherkin:

@id:a3f2b1c4
Example: User sees version on startup
  Given the application starts
  When no arguments are passed
  Then the version string is printed to stdout

Run tests once — a traced, skipped stub appears automatically:

@pytest.mark.skip(reason="not yet implemented")
def test_display_version_a3f2b1c4() -> None:
    """
    Given the application starts
    When no arguments are passed
    Then the version string is printed to stdout
    """

Each test traces to exactly one acceptance criterion. No orphan tests. No untested criteria.

When you run @setup-project, the agent collects your project's identity — name, tagline, mission, colour palette, and release naming convention — and writes docs/branding.md. All agents read this file. Release names, C4 diagram colours, and generated copy all reflect your project's identity without you touching .opencode/.

Absent or blank fields fall back to defaults: adjective-animal release names, Mermaid default colours, no wording constraints.

v{major}.{minor}.{YYYYMMDD} — each release gets a unique name derived from your branding convention. By default: an adjective paired with an animal (scientific name). Configure your own theme in docs/branding.md.

MIT — see LICENSE.

Author: @nullhack · Documentation