python3-development

Performs holistic code review and validation after feature implementation. Checks that code follows project development standards, utilizes shared utilities instead of reinventing, takes advantage of installed dependencies, and identifies gaps requiring additional tasks. Creates follow-up task files when issues are found. Use after implementation is complete.

Creates, enhances, and reviews Python CLI code using Typer and Rich — use for CLI tools, scripts with progress bars or tables, async processing, modernizing existing CLIs, or any Python implementation task. Expert in type annotations, Rich components (tables, progress bars, panels), async patterns, and clean architecture. <example> Context -- User wants to create a new CLI script for file processing. user -- "I need to build a CLI tool that processes multiple files and shows progress" assistant -- "I'll use python-cli-architect to create a modern CLI with Typer, Rich progress bars, and error handling." </example> <example> Context -- User needs to implement async CLI operations. user -- "I need a CLI that can process multiple API requests concurrently" assistant -- "I'll use python-cli-architect to implement async patterns with semaphores and progress feedback." </example>

Use when designing a Python CLI tool's architecture before implementation — command interfaces, technology stack selection, data models, and contracts. Activates on architecture planning requests for new CLI tools or major feature additions. Produces WHAT to build (interfaces, schemas, contracts); python-cli-architect handles the HOW (implementation).

Use when creating, reviewing, or modernizing Python 3.11+ pytest test suites. Activates on requests to write tests, improve coverage, migrate from unittest.mock to pytest-mock, add hypothesis property-based tests, integrate pytest-asyncio or pytest-bdd, or audit test quality. Enforces 80% coverage minimum, AAA pattern, and mutation testing for critical paths.

Uses CocoIndex Code MCP server to search codebases by semantic meaning — finds code by concept, behavior, or natural language description rather than exact keywords. Use when exploring unfamiliar codebases, finding implementations of a concept, or when exact identifiers are unknown. MCP server launches automatically via uvx when the python3-development plugin is installed.

Use when analyzing failing test cases to determine whether failures indicate genuine bugs or test implementation issues. Activates on "analyze failing tests", "debug test failures", "investigate test errors", or when provided with specific failing test names or output. Applies balanced investigative reasoning — does not auto-fix tests without establishing root cause.

Use when building async APIs, concurrent systems, or I/O-bound Python applications requiring non-blocking operations. Covers asyncio, async/await patterns, task scheduling, synchronization primitives, and high-performance concurrent programming.

Use when reviewing pytest test suites for coverage, isolation, mock usage, naming conventions, or completeness. Activates on requests like "review test coverage", "audit test quality", or "check tests for completeness". Performs thorough checklist-driven review for test isolation, mock correctness, AAA pattern adherence, and naming standards.

Use when creating a new feature task with structured tracking, phases, and documentation. Activates on "create a feature task", "set up development tracking", or "plan a feature implementation" requests. Produces a comprehensive feature development task with acceptance criteria, phase breakdown, and tracking artifacts ready for SAM pipeline execution.

Use when working with Hatchling — configuring build system setup, pyproject.toml metadata, dependencies, entry points, build hooks, version management, wheel and sdist builds, package distribution, setuptools migration, or troubleshooting Hatchling build errors. Covers PEP 517/518/621/660 standards.

Comprehensive guide for creating and managing MkDocs documentation projects with Material theme. Includes official CLI command reference with complete parameters and arguments, and mkdocs.yml configuration reference with all available settings and valid values. Use when working with MkDocs projects including site initialization, mkdocs.yml configuration, Material theme customization, plugin integration, or building static documentation sites from Markdown files.

Use when reviewing Python code for modernization opportunities, writing new Python 3.11+ code to ensure modern patterns, or refactoring legacy code to current idioms. Covers proper types, DRY, SRP, framework patterns, and idiomatic Python improvements.

Use when orchestrating a Python development task via specialized agents. Activates on "build a Python CLI", "add a feature", "write tests", "refactor Python code", "debug Python", "code review", or any multi-agent Python workflow. Invoke as /orchestrate with a task description or alone to use conversation context.

Use when setting up automated code quality checks on git commit, configuring .pre-commit-config.yaml, implementing git hooks for formatting or linting, creating prepare-commit-msg hooks, or distributing a tool as a pre-commit hook. Covers pre-commit and prek for multi-language projects.

Use when creating a README for a Python package, preparing for PyPI publication, fixing README rendering errors found by twine check, choosing between README.md and README.rst, or configuring the readme field in pyproject.toml. Generates professional, PyPI-compliant README files.

Use when the python-cli-architect agent needs project structure reference and task completion quality gates for Python CLI projects. Loaded automatically by the python-cli-architect agent — covers package layout, Hatchling configuration, and implementation quality criteria.

Guided workflow for adding new features to Python projects. Use when planning a new feature implementation, when adding functionality with proper test coverage, or when following TDD to build features incrementally.

Debug functional issues in Python code using specs, logs, and observed behavior. Use when a feature isn't working as specified, when investigating runtime errors, or when scoping a problem before implementing a fix.

Python 3 development plugin documentation index. Load when needing to read about Python implementation patterns, task file conventions, or stdlib scripting.

Use when building Python 3.11+ CLI apps (Typer/Rich), writing pytest test suites, fixing ruff linting or ty/mypy type errors, configuring pyproject.toml, creating portable scripts, or reviewing Python code. Activates on all Python implementation tasks — routes to specialist agents for CLI architecture, test design, packaging, and code review. Authoritative reference for modern Python 3.11-3.14 patterns and TDD workflows.

Configure pyproject.toml and Python packaging for distribution. Use when setting up a new Python package, when configuring build tools and dependencies, or when preparing a project for PyPI publishing.

Set up CI/CD pipeline for Python package publishing to PyPI. Use when preparing to publish a package, when setting up automated releases, or when configuring GitHub Actions or GitLab CI for Python projects.

Comprehensive Python code review checking patterns, types, security, and performance. Use when reviewing Python code for quality issues, when auditing code before merge, or when assessing technical debt in a Python codebase.

Use when designing pytest test suite architecture, planning test coverage strategy, or reviewing test structure for Python 3.11+ projects. Activates on "design a test strategy", "plan test coverage", "create test architecture", or when TDD/BDD/property-based testing patterns are mentioned. Guides fixture design, parametrization, async testing, and mutation testing coverage decisions.

Use when writing Python code with the Rich library — console output with markup, tables, progress bars, syntax highlighting, pretty printing, logging, or tracebacks. Covers Console, markup syntax, renderables (Panel/Table/Tree), Progress, Live, RichHandler, and the __rich_console__ protocol.

Use when searching a codebase by behavior, intent, or natural language description rather than exact identifiers. Activates the CocoIndex Code MCP server for semantic code search — finding implementations without knowing exact names, exploring unfamiliar codebases, or locating code by concept.

Validate Python shebangs and PEP 723 inline script metadata. Use when checking if Python files have correct shebangs based on their dependency requirements, when fixing incorrect shebang patterns, or when adding PEP 723 script blocks to standalone scripts with external dependencies.

Implementation phase for stinkysnake workflow. Use when tests are written and plan is ready. Implements functions following the modernization plan, runs tests until passing.

Use as the routing layer for Python development tasks — matches task descriptions against trigger lists and activates specialist skills before starting work. Covers Typer, Rich, Textual, FastMCP/MCP, ty type checker, uv, Hatchling, TOML editing, pre-commit/prek, async Python, PyPI packaging, complex linting, and technical debt modernization.

LAST RESORT for stdlib-only Python 3.11+ scripts in CONFIRMED restricted environments (airgapped systems, no uv, no internet access). Creates portable dependency-free scripts using argparse, logging, config management (JSON/TOML/INI), and cross-platform patterns. Use ONLY when environment restrictions prevent Typer+Rich with PEP 723. Triggers on "stdlib-only script", "no dependencies", "airgapped", "restricted environment", "portable script no network". For standard CLI development, use python-cli-architect with Typer+Rich instead.

Progressive Python quality improvement with static analysis, type refinement, modernization planning, plan review, and test-driven implementation. Use when addressing technical debt, eliminating Any types, applying modern Python patterns, or refactoring for better design.

Use when encountering failing tests, diagnosing test errors, or establishing a systematic approach to test failure investigation. Activates on "test failure analysis", "debugging tests", or "why tests fail" requests. Establishes the mindset that treats test failures as valuable diagnostic signals requiring root-cause investigation — not automatic code fixes or test dismissal.

Use when building Textual TUI apps — creating widgets, laying out screens, handling events, managing reactivity, testing with Pilot, or running background workers. Covers App lifecycle, CSS styling, screen stack, reactive attributes, custom messages, actions, bindings, and the Worker API.

Use when reading or writing pyproject.toml or .toml config files in Python, editing TOML while preserving comments and formatting, designing configuration file formats for Python tools, working with tomlkit or tomllib, or implementing atomic config file updates.

Use when working with ty — running Python type checks, configuring ty.toml or pyproject.toml, suppressing diagnostics, interpreting error codes, targeting Python versions, or integrating ty with editors and CI. Covers CLI flags, configuration schema, rule severity, suppression comments, environment discovery, module resolution, and all installation methods.

Use when building Typer/Rich CLI applications or reviewing existing CLI code for correctness. Activates on requests involving Rich table rendering, console output handling, testing Rich-formatted output, or Typer command wiring. Prevents common AI mistakes — Rich table wrapping in non-TTY contexts, incorrect stderr/stdout separation, and integration pitfalls. Load alongside the typer and rich API reference skills.

Use when building CLI applications with Typer — creating commands, defining arguments and options, composing subcommands, testing with CliRunner, or using advanced features like callbacks and autocompletion. Covers app creation, parameter types, subcommand composition, testing patterns, and output utilities.

Use when creating new Claude Code skills following established patterns and templates. Activates on "create a new skill", "add a skill to plugin", or "write skill from template" requests. Note — commands are deprecated; this skill creates SKILL.md files instead. Produces correctly structured skill files with valid frontmatter and body.

Use when working with Astral's uv — managing Python project dependencies, creating PEP 723 scripts, installing tools, managing Python versions, configuring package indexes, or migrating from pip/poetry. Covers project initialization, virtual environments, workspace configuration, and CI/CD integration.