Index of every page on this site: llms.txt
All skills
a2ui-project avatar

/coding-principles

@6bf4cc2
by A2UIa2ui-project/a2ui18k stars
1,430
Run it yourself

Enforces engineering, architecture, public API, and code quality standards distilled from human reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint generation without code or PR changes.

  • 17 files
  • 75.1 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/a2ui-project/a2ui/coding-principles

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

subskillspythonarchitecture-and-facades.md

≈1.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Subskill: Python Architecture, Package Boundaries & Public Facades

Activation Criteria

Activate this subskill when:

  • Modifying modules or package boundaries in python/a2ui_core/, python/a2ui_agent/, or python/catalogs/mcp/.
  • Adding, renaming, or reorganizing exported symbols in __init__.py or __all__.
  • Adding imports across Python packages, tests, scripts, or sample agents.
  • Implementing wire-format models, state containers, or fluent builders grounded in protocol specifications.

1. Target Architecture & Package Boundaries

Python code across the repository spans SDK libraries, agent implementations, evaluation harnesses, tooling, and scripts. The primary SDK library packages are managed as a uv workspace under python/:

  • a2ui_core (python/a2ui_core/):
    • Framework-agnostic runtime state and processing engine.
    • Implements DataModel (reactive JSON pointer mutations), SurfaceModel, MessageProcessor, and PayloadValidator.
    • Boundary rule: a2ui_core contains no LLM prompting, parsing, or agent orchestration logic.
  • a2ui_agent (python/a2ui_agent/):
    • Agent-side orchestration and prompting framework.
    • Implements A2uiGenerator, A2uiRequestProcessor, format strategies (DirectJsonFormat, ExpressFormat), and prompt generators.
    • Boundary rule: a2ui_agent is agent-framework agnostic. It must not import or depend on agent frameworks or model SDKs (a2a, google.adk, google.genai, ...). python/a2ui_agent/tests/test_framework_agnostic.py enforces this.
  • a2ui_a2a (python/a2ui_a2a/, distribution a2ui-a2a):
    • A2A protocol extension (a2ui.a2a): extension URI negotiation and A2A part helpers.
  • a2ui_adk (python/a2ui_adk/, distribution a2ui-adk):
    • Agent Development Kit integration (a2ui.adk): SendA2uiToClientToolset and A2uiProcessorStore.
    • The ADK-to-A2A converters (a2ui.adk.a2a) and A2A orchestration helpers (a2ui.adk.orchestration) need the a2a extra and are exported lazily from a2ui.adk.
  • Namespace rule: a2ui is a PEP 420 namespace package shared by all of these distributions. Never add src/a2ui/__init__.py, and never ship the same subpackage from two distributions.
  • a2ui.builder (python/a2ui_agent/src/a2ui/builder/):
    • Strongly typed Pydantic v2 fluent builders for components and basic catalogs.
    • Versioned by protocol (e.g. a2ui.builder.v0_9) to ensure protocol immutability.
  • catalogs/mcp (python/catalogs/mcp/):
    • Model Context Protocol (MCP) catalog bindings.
  • Evaluators, Tools, Scripts, and Samples (eval/, tools/, scripts/, samples/agent/):
    • Evaluation harnesses, developer utilities, repository automation scripts, and sample agents that consume or support the Python SDKs.
    • Must adhere to the same architectural standards, clean facade imports, and code hygiene rules.

2. Public Facades vs. Deep Module Imports

The Architectural Rule

Never expose, rely on, or demonstrate deep internal submodule import paths.

# BAD: Deep import into internal implementation details
from a2ui.builder.v0_9.catalogs.basic import Card, Column, Text, Button
from a2ui.core.processing.message_processor import MessageProcessor
from a2ui.core.state.data_model import DataModel

# GOOD: Importing from public package facades
from a2ui.builder.v0_9 import Action, ActionEvent, Button, Card, Column, Text
from a2ui.core import DataModel, MessageProcessor, PayloadValidator

How to Implement Public Facades

  1. Use __init__.py with Explicit __all__: Every public package must curate its public API in __init__.py and define an explicit __all__ list.
  2. Hide Internal Submodules: Submodules that are internal implementation details should either be prefixed with an underscore (_internal.py), placed in private directories (_compat.py), or omitted from __all__.
  3. Example and Documentation Hygiene: All README.md files, docstring examples, blueprints, and sample applications must exclusively demonstrate imports using public package facades.

The Constants Exception

Constants that are formally part of the public protocol API (e.g., SPEC_VERSION, PROTOCOL_VERSION) may be exported from a lightweight, dependency-free leaf module (e.g., a2ui.core.schema.v0_9.constants or a2ui.constants):

  • Callers requiring only protocol constants should be able to depend on the leaf module without pulling in the entire agent or runtime dependency tree.
  • When refactoring packages, keep existing leaf constant imports stable while ensuring the new structure exposes them through the canonical versioned schema facade.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 6bf4cc2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
metadata
{
  "internal": true
}

README badge

README badge for a2ui-project/a2ui/coding-principles