Skip to content

Engineering & Prose Guides

While workflow skills define what steps to take and tool skills define how to run tools, the guide-* skill suite establishes normative qualitative standards: the core philosophy, architectural idioms, typing patterns, and prose rules that shape every file in the repository.

AI coding assistants are trained on millions of public repositories, most of which contain legacy Python (Python 3.8/3.9 idioms, mutable default arguments, deep inheritance hierarchies, unconstrained Any types) and colloquial, ambiguous technical writing. guide-* skills counteract this by grounding agents in Zenith's modern, opinionated engineering philosophy.

Core Template Guides

These guides define the default engineering and writing standards for generated projects.

Modern Python 3.12+ Engineering (guide-python)

What it is: The definitive engineering style guide for Python 3.12+ code in Zenith. It codifies architectural invariants around type parameter syntax, structural subtyping, immutability, and module purity.

Why it's in Zenith: Python has undergone a profound modernization with releases 3.12 and 3.13. Modern Python offers first-class generic parameter syntax, high-speed type inference via Meta Pyrefly, and clean structural protocols. Without an explicit guide, AI models routinely generate legacy code: declaring old-style TypeVar('T'), nesting deep object-oriented class hierarchies, or using mutable dataclasses that introduce state bugs.

guide-python establishes five non-negotiable architectural pillars:

  1. PEP 695 Generics Syntax: Replaces verbose TypeVar declarations and Union wrappers with clean modern syntax:
from collections.abc import Callable

type JsonScalar = str | int | float | bool | None
type Json = dict[str, Json] | list[Json] | JsonScalar


# Modern Zenith idiom
def transform[T](items: list[T], operation: Callable[[T], T]) -> list[T]: ...
  1. Composition Over Inheritance: Avoids rigid inheritance hierarchies in favor of shallow composition and structural subtyping using typing.Protocol. Classes define what they do via behavioral interfaces rather than shared ancestry.
  2. Frozen Slots Dataclasses: Mandates @dataclass(frozen=True, slots=True) for domain entities and value objects. This provides immutability by default, prevents accidental attribute assignment, and optimizes runtime memory layout.
  3. Absolute Imports Only: Prohibits ambiguous relative imports (from .core import x). All module references use absolute package namespaces (from my_package.core import x), simplifying refactoring, layer verification in Tach, and AST static analysis.
  4. Strict Encoding Hygiene: Eliminates subtle platform-specific encoding bugs by requiring explicit encoding="utf-8" in all file read/write operations and subprocess calls.

Simplified Technical English (guide-ste100)

What it is: The writing guide and automated linter implementing the international Simplified Technical English standard (ASD-STE100 Issue 8).

Why it's in Zenith: Ambiguity in technical documentation causes execution failures for autonomous agents. When prompts or skill instructions contain modal verbs, passive voice, or ambiguous vocabulary, LLMs frequently misinterpret instructions, guess missing parameters, or skip critical verification steps entirely.

ASD-STE100 solves this through controlled language principles:

  • One Meaning Per Word: Restricts words to a single approved meaning per part of speech, eliminating polysemy and semantic confusion.
  • Active Voice & Imperative Verbs: Replaces passive constructions ("tests can be run") with direct, clear instructions ("Run the unit test suite with poe test").
  • Strict Sentence Length Limits: Caps procedural instructions at 20 words and descriptive sentences at 25 words to prevent model attention degradation.
  • Automated Verification: Zenith includes a standalone, standard-library Python linter and auto-fixer (ste-lint.py). Run uv run poe lint-ste to audit agent skills and Python docstrings against STE-100 vocabulary and structure rules. STE-100 is not enforced as a rule in user-facing documentation (docs/), where it serves only as a suggestion for clear phrasing.

Authoring Custom Guide Skills

As your project grows, your team will develop project-wide patterns for API design, database queries, or error handling. Codify them under the guide-* prefix so agents natively adhere to your team's architectural decisions:

mkdir -p .agents/skills/guide-api-design

Common examples created in Zenith projects:

  • guide-api-design: RESTful resource conventions, pagination envelopes, and HTTP status code standards.
  • guide-error-handling: Domain exception hierarchies, retry policies with jitter, and structured logging context schemas.
  • guide-security: Cryptographic key rotation, input sanitization rules, and OWASP mitigation strategies.