create-capabilities-python

create-capabilities-python

Capabilities = concrete protocol ABC implementation. File: capabilities_<domain>_<role>.py.

Allowed imports: Taxonomy, Contract (_protocol only), Utility. Forbidden: agent_*, other capabilities_*, surface_*, local domain models, magic constants.

Role Naming

Internal: validator, assessor, calculator, resolver, classifier, selector, mapper, transformer, policy, enricher, evaluator, analyzer, scorer, grader, ranker, filter, checker, reviewer, approver, rejector

External: repository, gateway, client, provider, fetcher, reader, writer, scanner, executor, publisher, subscriber, adapter, connector, uploader, downloader, sender, receiver, dispatcher, watcher, monitor

Structure Rules

• Rule 1: Internal helper classes without ABC → ALLOWED.
• Rule 2: ≥1 class inherits a protocol ABC.
• Rule 3: Total class count ≤ 3.

3-Block Structure

# Block 1: Class Definition & Constructor
# Block 2: Protocol ABC Method Implementation
# Block 3: Dunder Methods, Factories, Helpers

Method placement: @abstractmethod → Block 2. Dunder/factory/private → Block 3. Stateless free function → extract to *utility_.py.

Helper vs Utility

Keep in Block 3 if ANY: uses self, domain-specific, single consumer, factory. Extract to utility only if ALL: no self, pure, no side effects, domain-agnostic, ≥2 consumers. I/O: stateless + I/O + domain-agnostic = utility OK.

Templates

3-block implementation

from shared.<domain>.taxonomy_<name>_vo import <VO>
from shared.<domain>.contract_<name>_protocol import I<Name>Protocol


# ─── Block 1: Class Definition & Constructor ──────────────
class Capabilities<Name>(I<Name>Protocol):
    def __init__(self, /* DI params */) -> None:
        # DI fields use protocol interfaces
        # Value fields use shared VOs
        ...

    # ─── Block 2: Public Contract (domain protocol ONLY) ──
    def method_name(self, param: <VO>) -> None:
        # domain behavior
        ...

    # ─── Block 3: Dunder Methods, Factories & Helpers ─────
    def __repr__(self) -> str:
        return "Capabilities<Name>()"

    @classmethod
    def create_default(cls) -> "Capabilities<Name>":
        return cls()