Opinionated Python Development Skill

Opinionated Python Development Skill

Role Identification (Mandatory)

The model must identify its ROLE_TYPE and echo the following statement:

My ROLE_TYPE is "<the role type>". I follow instructions given to "the model" and "<role name>".

Where:

• <the role type> is either "orchestrator" or "sub-agent" based on the ROLE_TYPE identification rules in CLAUDE.md
• <role name> is "orchestrator" if ROLE_TYPE is orchestrator, or "sub-agent" if ROLE_TYPE is sub-agent

Example for orchestrator:

My ROLE_TYPE is "orchestrator". I follow instructions given to "the model" and "orchestrator".

Example for sub-agent:

My ROLE_TYPE is "sub-agent". I follow instructions given to "the model" and "sub-agent".

Orchestration guide for Python development using specialized agents and modern Python 3.11-3.14 patterns.

Skill Architecture

Bundled Resources (Included in This Skill)

Reference Documentation:

• User Project Conventions - Extracted conventions from user's production projects (MANDATORY for new projects)
• Modern Python Modules - 50+ library guides with usage patterns and best practices
• Tool & Library Registry - Development tools catalog for linting, testing, and build automation
• API Reference - API specifications and integration guides
• Python Development Orchestration - Detailed workflow patterns for TDD, feature addition, refactoring, and code review

Command Templates and Guides (commands/):

• Reference material for creating slash commands (NOT the actual slash commands)
• Command templates and patterns for development
• Testing and development workflow guides
• See Commands README for details

Scripts and Assets:

• Example scripts demonstrating patterns
• Configuration templates and boilerplate

Bundled Components (This Plugin)

This plugin bundles the core agents and workflows needed for Python 3.11+ development and SAM-style execution:

• Agents (bundled under ./plugins/python3-development/agents/): python-cli-architect, python-pytest-architect, python-cli-design-spec, swarm-task-planner, plus SAM workflow agents (feature research/analysis/verification).
• Skills (bundled): modernpython, shebangpython, and the SAM workflow skills (add-new-feature, implement-feature, start-task, complete-implementation).

System Tools (install via package manager or uv):

• uv - Python package and project manager (required)
• ruff - Linter and formatter
• pyright - Type checker (Microsoft)
• mypy - Static type checker
• pytest - Testing framework
• pre-commit - Git hook framework
• mutmut - Mutation testing (for critical code)
• bandit - Security scanner (for critical code)

Installation Notes:

• Agents and slash commands must be installed separately in their respective directories
• This skill provides orchestration guidance and references; agents perform actual implementation
• Use the uv skill for comprehensive uv documentation and package management guidance

Core Concepts

Python Development Standards

This skill provides orchestration patterns, modern Python 3.11+ standards, quality gates, and reference documentation for Python development.

Note on command templates:

This plugin includes command templates under ./commands/ as reference material. For actual invocation, prefer skills (e.g., modernpython, shebangpython).

Reference Documentation:

• Modern Python modules (50+ libraries)
• Tool and library registry with template variable system
• API specifications
• Working configurations for pyproject.toml, ruff, mypy, pytest

Docstring Standard: Google style (Args/Returns/Raises sections). See User Project Conventions for ruff pydocstyle configuration (convention = "google").

CRITICAL: Pyproject.toml Template Variables:

All pyproject.toml examples use explicit template variables (e.g., {{project_name_from_directory_or_git_remote}}) instead of generic placeholders. The model MUST replace ALL template variables with actual values before creating files. See Tool & Library Registry sections 18-19 for:

• Complete variable reference and sourcing methods
• Mandatory rules for file creation
• Validation and verification procedures

Script Dependency Trade-offs

Understand the complexity vs portability trade-off when creating Python CLI scripts:

Scripts with dependencies (Typer + Rich via PEP 723):

• Benefits:
  • Less development complexity - Leverage well-tested libraries for argument parsing, formatting, validation
  • Less code to write - Typer handles CLI boilerplate, Rich handles output formatting
  • Better UX - Colors, progress bars, structured output built-in
  • Just as simple to execute - PEP 723 makes it a single-file executable; uv handles dependencies automatically
• Trade-off: Requires network access on first run (to fetch packages)

stdlib-only scripts:

• Benefits:
  • Maximum portability - Runs on ANY Python installation without network access
  • Best for: Air-gapped systems, restricted corporate environments, embedded systems
• Trade-offs:
  • More development complexity - Build everything from scratch (manual argparse, manual tree formatting, manual color codes)
  • More code to write and test - Everything must be implemented manually
  • Basic UX - Limited formatting without external libraries

Default recommendation: Use Typer + Rich with PEP 723 unless you have specific portability requirements that prevent network access.

See:

• Python Development Orchestration Guide for detailed agent selection criteria
• Typer and Rich CLI Examples for Rich width handling solutions

Rich Panel and Table Width Handling

Common Problem: Rich containers (Panel, Table) wrap content at 80 characters in CI/non-TTY environments, breaking URLs, commands, and structured output.

Two Solutions Depending on Context:

Solution 1: Plain Text (No Containers)

For plain text output that shouldn't wrap:

from rich.console import Console

console = Console()

# URLs, paths, commands - never wrap
console.print(long_url, crop=False, overflow="ignore")

Solution 2: Rich Containers (Panel/Table)

For Panel and Table that contain long content, crop=False alone doesn't work because containers calculate their own internal layout. Use get_rendered_width() helper with different patterns for Panel vs Table:

from rich.console import Console, RenderableType
from rich.measure import Measurement
from rich.panel import Panel
from rich.table import Table

def get_rendered_width(renderable: RenderableType) -> int:
    """Get actual rendered width of Rich renderable.

    Handles color codes, Unicode, styling, padding, borders.
    Works with Panel, Table, or any Rich container.
    """
    temp_console = Console(width=99999)
    measurement = Measurement.get(temp_console, temp_console.options, renderable)
    return int(measurement.maximum)

console = Console()

# Panel: Set Console width (Panel fills Console width)
panel = Panel(long_content)
panel_width = get_rendered_width(panel)
console.width = panel_width  # Set Console width, NOT panel.width
console.print(panel, crop=False, overflow="ignore", no_wrap=True, soft_wrap=True)

# Table: Set Table width (Table controls its own width)
table = Table()
table.add_column("Type", style="cyan", no_wrap=True)
table.add_column("Value", style="green", no_wrap=True)
table.add_row("Data", long_content)
table.width = get_rendered_width(table)  # Set Table width
console.print(table, crop=False, overflow="ignore", no_wrap=True, soft_wrap=True)

Executable Examples: See ./assets/typer_examples/ for complete working scripts:

• console_no_wrap_example.py - Plain text wrapping solutions
• console_containers_no_wrap.py - Panel/Table width handling with get_rendered_width()

Rich Emoji Usage

Instruction: In Rich console output, always use Rich emoji tokens instead of literal Unicode emojis.

Use Rich emoji tokens: :white_check_mark: :cross_mark: :magnifying_glass:

Why: Cross-platform compatibility, consistent rendering, markdown-safe alignment

Example:

from rich.console import Console

console = Console()

# Correct - Rich emoji tokens
console.print(":white_check_mark: Task completed")
console.print(":cross_mark: Task failed")
console.print(":sparkles: New feature")
console.print(":rocket: Performance improvement")

Benefits:

• Rich emoji tokens work consistently across all terminals and fonts
• Avoid markdown table alignment issues (emoji width calculation problems)
• Enable proper width measurement in get_rendered_width()
• Ensure cross-platform compatibility (Windows, Linux, macOS)

See: Rich Emoji Documentation for complete emoji token reference.

Python Exception Handling

Catch exceptions only when you have a specific recovery action. Let all other errors propagate to the caller.

Reason: Fail-fast principle surfaces issues early rather than hiding them behind generic error messages.

Pattern:

def get_user(id):
    return db.query(User, id)  # Errors surface naturally

def get_user_with_handling(id):
    try:
        return db.query(User, id)
    except ConnectionError:
        logger.warning("DB unavailable, using cache")
        return cache.get(f"user:{id}")  # Specific recovery action

When adding try/except, answer: "What specific error do I expect, and what is my recovery action?"

See: Exception Handling in Python CLI Applications for comprehensive patterns including Typer exception chain prevention.

Type Safety with Mypy

REQUIREMENT: All Python code MUST be comprehensively typed using Python 3.11+ native type hints.

Python Version: Python 3.11+ is required unless explicitly documented otherwise. Older versions are rare, documented exceptions.

The model MUST read the official mypy documentation examples before implementing type patterns. Each subsection links to authoritative mypy docs.

When to Use Generics

Use generics for type-safe container classes and functions that work with multiple types.

Applicable scenarios:

• Custom collection classes (stacks, queues, boxes)
• Functions accepting multiple type variants
• Decorators and factory methods
• Reusable protocols and type aliases

MUST read examples before implementing: Mypy Generics Documentation

Python 3.11 Generic Pattern (TypeVar with Generic):

from typing import TypeVar, Generic, Sequence

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

def first(seq: Sequence[T]) -> T:
    return seq[0]

Python 3.12+ Generic Pattern (Native Syntax):

class Stack[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

def first[T](seq: Sequence[T]) -> T:
    return seq[0]

Type Variable Bounds (restrict to subtypes):

from collections.abc import Sequence
from typing import Protocol

class SupportsAbs[T](Protocol):
    def __abs__(self) -> T: ...

def max_by_abs[T: SupportsAbs[float]](*xs: T) -> T:
    return max(xs, key=abs)

Value Restrictions (limit to specific types):

def concat[S: (str, bytes)](x: S, y: S) -> S:
    return x + y  # Type-safe for str OR bytes, but not mixed

Generic Method Chaining (precise return types):

from typing import Self

class Shape:
    scale: float = 1.0

    def set_scale(self, scale: float) -> Self:
        self.scale = scale
        return self  # Returns precise subclass type

When to Use Protocols

Use protocols for structural subtyping when you need duck typing with type safety. Protocols check whether an object has required methods/attributes regardless of inheritance.

Applicable scenarios:

• Accept any object with specific capabilities without requiring inheritance
• Define interfaces for duck-typed code
• Create flexible callback types
• Ensure compatibility without tight coupling

MUST read examples before implementing: Mypy Protocols Documentation

Basic Protocol Pattern:

from typing import Protocol

class SupportsClose(Protocol):
    def close(self) -> None: ...

def close_resource(resource: SupportsClose) -> None:
    resource.close()  # Works with ANY object having close() method

# No inheritance needed - structural match
class FileHandler:
    def close(self) -> None:
        print("Closing file")

close_resource(FileHandler())  # ✅ Type-safe

Read-Only Attributes (use @property to avoid invariance issues):

from typing import Protocol

class Named(Protocol):
    @property
    def name(self) -> str: ...  # Read-only via property

Recursive Protocols (tree structures):

from typing import Protocol

class TreeLike(Protocol):
    value: int

    @property
    def left(self) -> TreeLike | None: ...

    @property
    def right(self) -> TreeLike | None: ...

Runtime Checks:

from typing import Protocol, runtime_checkable

@runtime_checkable
class Drawable(Protocol):
    def draw(self) -> None: ...

def render(obj: object) -> None:
    if isinstance(obj, Drawable):  # Runtime check enabled
        obj.draw()

WARNING: isinstance() with protocols only verifies attribute existence, NOT type correctness. Use for structural validation, not precise type guarantees.

TypedDict for Dictionary Typing

Use TypedDict for dictionaries with fixed schemas and string keys where each key has a specific value type.

Applicable scenarios:

• Dictionaries representing objects with predictable structure
• JSON-like data structures
• Configuration dictionaries
• API request/response payloads

MUST read examples before implementing: Mypy TypedDict Documentation

Required Fields Pattern (all keys required):

from typing import TypedDict

class Movie(TypedDict):
    name: str
    year: int
    director: str

movie: Movie = {
    "name": "Blade Runner",
    "year": 1982,
    "director": "Ridley Scott"
}  # All keys required

Optional Fields Pattern (total=False):

from typing import TypedDict

class MovieOptions(TypedDict, total=False):
    subtitles: bool
    audio_language: str

options: MovieOptions = {}  # ✅ Empty dict valid
options2: MovieOptions = {"subtitles": True}  # ✅ Partial valid

Mixed Required/Optional Pattern:

from typing import TypedDict

class MovieBase(TypedDict):
    name: str  # Required
    year: int  # Required

class Movie(MovieBase, total=False):
    director: str  # Optional
    rating: float  # Optional

movie: Movie = {"name": "Alien", "year": 1979}  # ✅ Valid

CRITICAL: Always annotate variables when assigning TypedDict literals. Without annotation, mypy infers dict[str, Any]:

# ❌ Wrong - inferred as dict[str, Any]
movie = {"name": "Alien", "year": 1979}

# ✅ Correct - explicitly typed
movie: Movie = {"name": "Alien", "year": 1979}

Type Narrowing

Use type narrowing to refine broad union types to specific types based on runtime checks.

Applicable scenarios:

• Handling union types (e.g., str | int | None)
• Optional value processing
• Validating input types
• Control flow-based type refinement

MUST read examples before implementing: Mypy Type Narrowing Documentation

isinstance() Narrowing:

def process_value(value: str | int) -> str:
    if isinstance(value, str):
        return value.upper()  # Narrowed to str
    else:
        return str(value * 2)  # Narrowed to int

None Checks:

def greet(name: str | None) -> str:
    if name is not None:
        return f"Hello, {name}"  # Narrowed to str
    return "Hello, stranger"

Type Guards (custom narrowing functions):

from typing import TypeGuard

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(values: list[object]) -> None:
    if is_str_list(values):
        # Narrowed to list[str] in this branch
        print(" ".join(values))

TypeIs (Python 3.13+, more powerful than TypeGuard):

from typing import TypeIs

def is_str(val: object) -> TypeIs[str]:
    return isinstance(val, str)

def process(val: str | int) -> None:
    if is_str(val):
        print(val.upper())  # Narrowed to str
    else:
        print(val * 2)  # Narrowed to int (complement type)

Key difference: TypeGuard narrows only the if-branch; TypeIs narrows both branches (if-branch to the specified type, else-branch to the complement).

attrs vs dataclasses vs pydantic

Decision Matrix:

attrs Pattern (high performance, pure Python):

from attrs import define, field

@define
class User:
    name: str
    age: int = field(validator=lambda i, a, v: v >= 0)
    email: str | None = None

MUST read examples: Mypy Additional Features - Attrs

dataclasses Pattern (stdlib-only):

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class User:
    name: str
    age: int
    email: str | None = None

    def __post_init__(self) -> None:
        if self.age < 0:
            raise ValueError("Age must be non-negative")

pydantic Pattern (external data validation):

from pydantic import BaseModel, Field, field_validator

class User(BaseModel):
    name: str
    age: int = Field(ge=0)
    email: str | None = None

    @field_validator('age')
    @classmethod
    def validate_age(cls, v: int) -> int:
        if v < 0:
            raise ValueError('Age must be non-negative')
        return v

Recommendation:

• Default: Use attrs for internal data structures (best performance, most features)
• Stdlib-only requirement: Use dataclasses
• External data (APIs, configs, user input): Use pydantic (if already a dependency)

NEVER add pydantic as a dependency solely for dataclasses. Use attrs or stdlib dataclasses instead.

Additional Mypy Features

MUST read before using advanced patterns: Mypy Additional Features

Generic Dataclasses:

from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar('T')

@dataclass
class Box(Generic[T]):
    value: T

int_box: Box[int] = Box(value=42)
str_box: Box[str] = Box(value="hello")

Self Type for Method Chaining:

from typing import Self

class Builder:
    def set_name(self, name: str) -> Self:
        self.name = name
        return self

    def set_value(self, value: int) -> Self:
        self.value = value
        return self

# Type-safe chaining
builder = Builder().set_name("test").set_value(42)

Mypy Configuration Best Practices

Strict Mode Configuration (pyproject.toml):

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_any_generics = true
check_untyped_defs = true
no_implicit_reexport = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
warn_unreachable = true

Per-Module Overrides (for gradual typing):

[[tool.mypy.overrides]]
module = "third_party_lib.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "legacy_code.*"
disallow_untyped_defs = false

See: Tool & Library Registry - Mypy Configuration for complete configuration examples.

Agent Orchestration (Orchestrator Only)

STOP - MANDATORY PRE-DELEGATION PROTOCOL

Before using the Task tool for ANY Python development delegation, the orchestrator MUST complete this checklist. This is NOT optional. Skipping this protocol leads to agent context exhaustion, architectural mistakes, and failed delegations.

Pre-Delegation Checklist (Complete ALL before Task tool)

BLOCKING RULE: If you cannot answer steps 2-5 from memory, you have NOT read the orchestration guide. Go back to step 1.

Why This Protocol Exists

Problem observed: Orchestrators skip reading the guide, send one massive task to a single agent, the agent runs out of context, makes architectural mistakes, and user must intervene.

Solution: Reading the guide FIRST reveals:

• Complex tasks require multiple agents in sequence (design → test → implement → review)
• Each agent should receive focused, bounded scope
• Quality gates between agents catch issues early

Enforcement

The orchestrator must state which workflow pattern they are using before the first Task tool invocation:

"I have read the orchestration guide. Using [WORKFLOW PATTERN] with agents: [AGENT1] → [AGENT2] → [AGENT3]"

If you find yourself about to delegate without this statement, STOP and read the guide first.

DO NOT Pre-Gather Data for Agents

Anti-pattern: Reading files, running commands, or exploring the codebase to "understand the problem" before delegating, then summarizing findings for the agent.

Why this is wrong:

1. Agents perform Chain of Verification (CoVe): Agents follow the Scientific Execution Protocol. They read files, form hypotheses, and verify their understanding against actual source code. Your pre-gathered summary bypasses their verification process.

2. Shallow read vs. focused discovery: You read without knowing what the agent needs. The agent reads with focused intent—they know what they're building and what details matter.

3. Stale/incomplete data treated as fact: Your summary may be incomplete or misunderstood. The agent may incorrectly treat your pre-gathered observations as verified facts rather than re-verifying.

4. Context waste: Pre-gathering uses YOUR context, then the agent re-reads anyway. Double the context cost, half the accuracy.

The agent has read access to everything. Let them discover and verify.

What TO provide:

• Outcomes: What must be true when done
• Constraints: User requirements, compatibility needs
• Known issues: Error messages the user reported (pass-through, not pre-gathered)
• File paths: Where to start looking (not what you found there)

Delegation Pattern

The orchestrator delegates Python development tasks to specialized agents rather than implementing directly.

Reason: Agents have focused expertise and appropriate tool access for their specific domains.

The orchestrator follows this pattern:

1. READ the orchestration guide (mandatory - no exceptions)
2. Choose appropriate agents based on task requirements
3. Provide clear context: file paths, success criteria, scope boundaries
4. Chain agents for complex workflows (design → implement → test → review)
5. Validate outputs with quality gates

The orchestrator delegates rather than implements:

Reason for delegation table: Clear mapping prevents orchestrator from implementing when it should coordinate.

Required Reading (MANDATORY)

The orchestrator MUST read this guide BEFORE any delegation. Not reading it is the #1 cause of failed Python development tasks.

Python Development Orchestration Guide

This guide contains:

• Agent selection criteria and decision trees
• Workflow patterns (TDD, feature addition, code review, refactoring, debugging)
• Quality gates and validation requirements
• Delegation best practices
• Multi-agent chaining patterns (critical for complex tasks)

Quick Reference Example

User: "Build a CLI tool to process CSV files"

Orchestrator workflow:
0. Read("${CLAUDE_PLUGIN_ROOT}/skills/python3-development/references/python-development-orchestration.md")
   "I have read the orchestration guide. Using FEATURE ADDITION workflow with agents:
    @agent-python-cli-architect → @agent-python-pytest-architect → @agent-python-code-reviewer"

1. Delegate to @agent-python-cli-architect (FOCUSED SCOPE: implementation only)
   "Create CSV processing CLI with Typer+Rich progress bars. Scope: src/csv_tool.py only."

2. Delegate to @agent-python-pytest-architect (FOCUSED SCOPE: tests only)
   "Create test suite for CSV processor. Scope: tests/test_csv_tool.py only."

3. Instruct agent to run: /shebangpython, /modernpython

4. Delegate to @agent-python-code-reviewer (FOCUSED SCOPE: review only)
   "Review CSV processor implementation for patterns and quality."

5. Validate: Code quality checks per holistic-linting skill, then uv run pytest

Notice: Each delegation has FOCUSED SCOPE. The orchestrator read the guide FIRST and stated the workflow pattern BEFORE any Task tool usage.

Command Usage

/modernpython

Purpose: Comprehensive reference guide for Python 3.11+ patterns with official PEP citations

When to use:

• As reference guide when writing new code
• Learning modern Python 3.11-3.14 features and patterns
• Understanding official PEPs (585, 604, 695, etc.)
• Identifying legacy patterns to avoid
• Finding modern alternatives for old code

Note: This is a reference document to READ, not an automated validation tool. Use it to guide your implementation choices.

Usage:

/modernpython
→ Loads comprehensive reference guide
→ Provides Python 3.11+ pattern examples
→ Includes PEP citations with research tool guidance (prefer MCP tools: Ref/exa over WebFetch)
→ Shows legacy patterns to avoid
→ Shows modern alternatives to use
→ Framework-specific guides (Typer, Rich, pytest)

Research tool preference for PEP documentation:
1. mcp__Ref__ref_search_documentation(query="PEP {number} Python enhancement proposal")
2. mcp__exa__get_code_context_exa(query="PEP {number} implementation examples")
3. WebFetch as fallback

> [Web resource access, definitive guide for getting accurate data for high quality results](./references/accessing_online_resources.md)

With file path argument:

/modernpython src/mymodule.py
→ Loads guide for reference while working on specified file
→ Use guide to manually identify and refactor legacy patterns

/shebangpython

Purpose: Validate correct shebang for ALL Python scripts based on their dependencies and execution context

When to use:

• Creating any standalone executable Python script
• Validating script shebang correctness
• Ensuring scripts have proper execution configuration

Required for: ALL executable Python scripts (validates shebang matches script type)

What it validates:

• Stdlib-only scripts: #!/usr/bin/env python3 (no PEP 723 needed - nothing to declare)
• Scripts with dependencies: #!/usr/bin/env -S uv --quiet run --active --script + PEP 723 metadata declaring those dependencies
• Package executables: #!/usr/bin/env python3 (dependencies via package manager)
• Library modules: No shebang (not directly executable)

See: PEP 723 Reference for details on inline script metadata

Pattern:

/shebangpython scripts/deploy.py
→ Analyzes imports to determine dependency type
→ **Corrects shebang** to match script type (edits file if wrong)
→ **Adds PEP 723 metadata** if external dependencies detected (edits file)
→ **Removes PEP 723 metadata** if stdlib-only (edits file)
→ Sets execute bit if needed
→ Provides detailed verification report

Core Workflows (Orchestrator Only)

The orchestrator follows established workflow patterns for Python development tasks. See Python Development Orchestration Guide for complete details.

Task Planning Protocol (MANDATORY)

Every task MUST begin with discovery and planning before implementation.

Why: Skipping discovery leads to rework, missed patterns, and integration failures. The planning phase identifies context, patterns, and dependencies that inform implementation.

Phase 1: Discovery (before any implementation)

1. Context Gathering: Identify existing code patterns, project structure, and conventions
2. Dependency Analysis: Determine what files/modules are affected
3. Tool Detection: Run Linting Discovery Protocol to identify project tools
4. MCP Resource Check: Identify available MCP tools for documentation and research

Phase 2: Planning (before writing code)

1. Task Breakdown: Use swarm-task-planner agent for complex tasks
2. Agent Selection: Match task requirements to specialized agents
3. Quality Gates: Define acceptance criteria and verification steps
4. Validation Strategy: Identify tests and checks needed

Phase 3: Implementation

1. Execute plan using selected agents
2. Validate incrementally against acceptance criteria
3. Run quality gates (linting, type checking, tests)

Phase 4: Verification

1. Run all tests: uv run pytest
2. Check coverage: Minimum 80% for standard code, 95%+ for critical paths
3. Lint validation: Run detected git hook tool
4. Final review: Use python-code-reviewer agent

Workflow Overview

1. TDD (Test-Driven Development): Design → Write Tests → Implement → Review → Validate
2. Feature Addition: Requirements → Architecture → Plan → Implement → Test → Review
3. Code Review: Self-Review → Standards Check → Agent Review → Fix → Re-validate
4. Refactoring: Tests First → Refactor → Validate → Review
5. Debugging: Reproduce → Trace → Fix → Test → Review

Each workflow uses agent chaining with specific quality gates. See the orchestration guide for complete patterns, examples, and best practices.

Linting Discovery Protocol

The model executes this discovery sequence before any linting or formatting operations:

Reason: Projects use different tool configurations. Discovery ensures compatibility with project standards and CI pipelines.

Discovery Sequence

1. Check for git hook tool configuration:

   # Verify .pre-commit-config.yaml exists
   test -f .pre-commit-config.yaml && echo "git hook config detected"
   

   If found: Detect and run the correct git hook tool:

   # Detect tool (outputs 'prek' or 'pre-commit')
   uv run python -c "print(open('.git/hooks/pre-commit').readlines()[1].split()[4].rstrip(':') if __import__('pathlib').Path('.git/hooks/pre-commit').exists() else 'prek')"
   
   # Or use the holistic-linting detection script if available
   uv run holistic-linting/scripts/detect-hook-tool.py run --files <files>
   

   Detection logic: reads .git/hooks/pre-commit line 2, token 5 identifies the tool. Defaults to prek.

   Note: prek is a Rust-based drop-in replacement for pre-commit. Both tools use the same .pre-commit-config.yaml and have identical CLI interfaces.

   Use detected tool with: uv run <detected-tool> run --files <files> for ALL quality checks

   • This runs the complete toolchain configured in the project
   • Includes formatting, linting, type checking, and custom validators
   • Matches exactly what runs in CI and blocks merges

2. Else check CI pipeline configuration:

   # Check for GitLab CI or GitHub Actions
   test -f .gitlab-ci.yml || find .github/workflows -name "*.yml" 2>/dev/null
   

   If found: Read the CI config to identify required linting tools and their exact commands

   • Look for ruff, mypy, basedpyright, pyright, bandit invocations
   • Note the exact commands and flags used
   • Execute those specific commands to ensure CI compatibility

3. Else fallback to tool detection:

   • Check pyproject.toml [project.optional-dependencies] or [dependency-groups] for dev tools
   • Use discovered tools with standard configurations

Format-First Workflow

The model always formats before linting.

Reason: Formatting operations (like ruff format) automatically fix many linting issues (whitespace, line length, quote styles). Running linting before formatting wastes context and creates false positives.

Mandatory sequence:

1. Format: uv run ruff format <files> or via git hook tool (pre-commit/prek)
2. Lint: uv run ruff check <files> or via git hook tool
3. Type check: Use project-configured type checker
4. Test: uv run pytest

When using git hook tool (pre-commit or prek):

# Detect which tool is installed, then run it
# Tool runs hooks in configured order (formatting first)
uv run <detected-tool> run --files <files>

The .pre-commit-config.yaml already specifies correct ordering - trust it.

Type Checker Discovery

The model detects which type checker the project uses:

Reason: Projects standardize on different type checkers (basedpyright, pyright, mypy). Using the wrong one produces incompatible results.

Detection priority:

1. Check .pre-commit-config.yaml for basedpyright, pyright, or mypy hooks
2. Check pyproject.toml for [tool.basedpyright], [tool.pyright], or [tool.mypy] sections
3. Check .gitlab-ci.yml or GitHub Actions for type checker invocations

Common patterns:

• basedpyright: GitLab projects (native GitLab reporting format)
• pyright: General TypeScript-style projects
• mypy: Python-first type checking

Example detection:

# Check .pre-commit-config.yaml (works with both pre-commit and prek)
grep -E "basedpyright|pyright|mypy" .pre-commit-config.yaml

# Check pyproject.toml
grep -E "^\[tool\.(basedpyright|pyright|mypy)\]" pyproject.toml

Always detect from project configuration rather than assuming.

Quality Gates

The model follows the Linting Discovery Protocol before executing quality gates.

Every Python task must pass:

1. Format-first: uv run ruff format <files> (or via git hook tool)
2. Linting: uv run ruff check <files> (clean, after formatting)
3. Type checking: Use detected type checker (basedpyright, pyright, or mypy)
4. Tests: uv run pytest (>80% coverage)
5. Modern patterns: /modernpython (no legacy typing)
6. Script compliance: /shebangpython (for standalone scripts)

Preferred execution method:

# If .pre-commit-config.yaml exists (runs all checks in correct order):
# First detect which tool is installed (pre-commit or prek), then:
uv run <detected-tool> run --files <changed_files>

# Else use individual tools in this exact sequence:
uv run ruff format <files>           # 1. Format first
uv run ruff check <files>            # 2. Lint after formatting
uv run <detected-type-checker> <files>  # 3. Type check (basedpyright/pyright/mypy)
uv run pytest                         # 4. Test

For critical code (payments, auth, security):

• Coverage >95%
• Mutation testing: uv run mutmut run (>90% score)
• Security scan: uv run bandit -r packages/

CI Compatibility Verification:

After local quality gates pass, verify CI will accept the changes:

1. If .gitlab-ci.yml exists: Check for additional validators not in pre-commit
2. If .github/workflows/*.yml exists: Check for additional quality gates
3. Ensure all CI-required checks are executed locally before claiming task completion

Linting Exception Conditions

The model MUST NOT ignore or bypass linting errors UNLESS the code falls into one of these categories:

Acceptable Exceptions (OK to ignore linting):

1. Vendored code - Third-party code copied into the repository without modification
2. Examples of what-not-to-do - Intentionally incorrect code for educational purposes
3. Code pinned to historic Python version - Code requiring Python < 3.11 compatibility
4. Code for Python derivatives - CircuitPython, MicroPython, or similar implementations

Unacceptable Exceptions (MUST fix or

…(truncated)