hotfix(v6.4.20260420): rewrite README in brand voice and enrich branding.md

README.md

@@ -13,7 +13,7 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/nullhack/python-project-template/ci.yml?style=for-the-badge&label=CI)](https://github.com/nullhack/python-project-template/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.13-blue?style=for-the-badge)](https://www.python.org/downloads/)
 
-**Production-ready Python scaffolding with a structured AI-agent workflow — from idea to shipped feature.**
+**From zero to hero — production-ready Python, without the ceremony.**
 
 </div>
 
@@ -34,19 +34,21 @@ uv run task test && uv run task lint && uv run task static-check
 
 ## Why this template?
 
-Most Python templates give you a folder structure and a `Makefile`. This one gives you a **complete delivery system**:
+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** — they are generated automatically from your `.feature` files
+- **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** — PO, SE, and reviewer each have scoped instructions; none can exceed their authority
+- **AI agents for every role** — each agent has scoped instructions and cannot exceed its authority
 
 ---
 
 ## How it works
 
-### 5-step delivery cycle
+### The delivery cycle
 
 ```
 SCOPE → ARCH → TDD LOOP → VERIFY → ACCEPT
@@ -75,6 +77,7 @@ docs/features/completed/    ← shipped
 | `@product-owner` | Scope, stories, acceptance criteria, delivery acceptance |
 | `@software-engineer` | Architecture, TDD loop, git, releases |
 | `@reviewer` | Adversarial verification — default position: broken |
+| `@designer` | Visual identity, colour palette, SVG assets |
 | `@setup-project` | One-time project initialisation |
 
 ### Quality tooling, pre-configured
@@ -141,13 +144,21 @@ def test_display_version_a3f2b1c4() -> None:
     """
 ```
 
-Each test is traced to exactly one acceptance criterion. No orphan tests. No untested criteria.
+Each test traces to exactly one acceptance criterion. No orphan tests. No untested criteria.
+
+---
+
+## Branding
+
+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.
 
 ---
 
 ## Versioning
 
-`v{major}.{minor}.{YYYYMMDD}` — each release gets a unique adjective-animal name.
+`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`.
 
 ---
 

docs/branding.md

@@ -1,43 +1,51 @@
-# Branding
+# Branding — Python Project Template
 
-All fields are optional. Blank or absent fields fall back to defaults (adjective-animal release names, Mermaid default colors, no wording constraints). Agents read this file before generating release names, C4 diagrams, README banners, or any document with visual or copy identity.
+> *From zero to hero — production-ready Python, without the ceremony.*
+
+Agents read this file before generating release names, C4 diagrams, README banners, or any document with visual or copy identity. All fields are optional; absent or blank fields fall back to defaults (adjective-animal release names, Mermaid default colors, no wording constraints).
 
 ---
 
 ## Identity
 
 - **Project name:** Python Project Template
-- **Tagline:** Production-ready Python, from zero to workflow in minutes.
+- **Tagline:** From zero to hero — production-ready Python, without the ceremony.
 - **Mission:** Eliminate boilerplate so engineers ship features, not setup.
-- **Vision:** The standard starting point for any serious Python project.
-- **Tone of voice:** Direct, precise, minimal. No fluff.
+- **Vision:** The standard starting point for any serious Python project — the bedrock every Python engineer reaches for first.
+- **Tone of voice:** Direct, precise, minimal. The Greeks did not decorate the Parthenon with apologies. Neither do we.
 
 ## Visual
 
-- **Background/parchment:** `#faf7f2` → `#ede8e0`  — warm off-white marble (primary surface)
-- **Primary text:** `#5c3d1e` → `#3b2410`           — deep warm brown (body text, headings)
-- **Accent/gold:** `#c9a84c` → `#e8c96a`            — antique gold (borders, highlights, lines)
-- **Secondary/blue:** `#7baabf` → `#4a7a96`         — muted steel blue (labels, secondary text)
-- **Stone/marble:** `#f0ece4` → `#c8c0b8`           — structural marble tone (temple columns, shapes)
+The palette is drawn from classical marble, parchment, and gold — materials that have carried ideas for millennia. Every colour choice serves legibility first; decoration is secondary.
+
+- **Background/parchment:** `#faf7f2` → `#ede8e0`  — warm off-white, the surface on which ideas are set down
+- **Primary text:** `#5c3d1e` → `#3b2410`           — deep warm brown, the ink that endures
+- **Accent/gold:** `#c9a84c` → `#e8c96a`            — antique gold, used for borders and structural lines only — never body text
+- **Secondary/blue:** `#7baabf` → `#4a7a96`         — Aegean steel blue, for labels and secondary hierarchy
+- **Stone/marble:** `#f0ece4` → `#c8c0b8`           — the load-bearing colour; columns, shapes, structural chrome
 - **Logo:** `docs/assets/logo.svg`
 - **Banner:** `docs/assets/banner.svg`
 
-> Color system derived from the SVG assets (classical Greek temple aesthetic — marble, parchment, antique gold). Deep brown `#3b2410` on parchment `#faf7f2` achieves > 10:1 contrast (WCAG AAA). Gold accent used for decorative lines and borders only, not body text.
+> Deep brown `#3b2410` on parchment `#faf7f2` achieves >10:1 contrast (WCAG AAA). Gold is decorative; it never carries meaning that must be read.
 
 ## Release Naming
 
 - **Convention:** `adjective-greek-figure`
-- **Theme:** Greek antiquity — philosophers, heroes, gods, mythological figures (e.g. "Nimble Socrates", "Resolute Athena", "Precise Pythagoras")
+- **Theme:** Greek antiquity — philosophers, heroes, gods, mythological figures. Every release name should read like an epithet: something a figure *earned* through their defining quality (e.g. "Resolute Athena", "Precise Pythagoras", "Luminous Hypatia").
+- **Rationale:** Ancient Greece is the origin of the intellectual tradition that underpins Western civilisation — democracy, systematic philosophy, formal logic, and scientific reasoning all trace their lineage to the Greek city-states. Plato and Aristotle invented political philosophy as a genre; Aristotle formalised logic and ethics; the Pythagoreans established that abstract reasoning could describe the physical world. This template stands on the same premise: rigorous method, applied from the beginning, produces something worth building on. The Greek figure in each release name is not decoration — it is a statement about what kind of work this is.
 - **Excluded words:** *(none)*
 
 ## Wording
 
-- **Avoid:** `easy`, `simple`, `just`, `quick` — these undermine engineer credibility
-- **Prefer:** `minimal`, `precise`, `production-ready`, `zero-boilerplate`
+Every word carries weight. The Greeks had a name for ornament that obscures meaning: *kenophonia* — empty noise.
+
+- **Avoid:** `easy`, `simple`, `just`, `quick`, `scaffold` — these words undermine engineer credibility or imply the work is trivial. A temple is not a scaffold.
+- **Prefer:** `minimal`, `precise`, `production-ready`, `zero-boilerplate`, `rigorous`, `from zero to hero`
 
 ## Project Summary
 
 A Python project template with a production-ready AI-assisted delivery workflow.
 Ships with quality tooling (ruff, pyright, pytest, hypothesis), Gherkin-driven
-acceptance criteria, and four specialized AI agents covering scope through release.
-Use this summary in banners, release notes, and document headers.
+acceptance criteria, and five specialised AI agents covering scope through release.
+Built on the premise that rigorous method, applied from the beginning, produces
+something worth building on. Use this summary in banners, release notes, and document headers.