interface-contracts

Interface Contracts for Parallel Development

When planning new features or tasks, proactively identify interface boundaries that enable parallel development between agents. Formal interface contracts allow multiple agents to work simultaneously on different components that will integrate together.

When to Create an Interface Contract

Create interface contract if ANY:
  - Multiple components need to communicate? → Yes
  - Work can be parallelized across agents? → Yes
  - 3+ tasks blocked by same dependency? → Yes
Otherwise: No interface needed

Interface Contract Requirements

Every interface contract must include:

1. Abstract base class or Protocol with @abstractmethod decorators
2. Complete type hints for all parameters and return values
3. Comprehensive docstrings documenting behavior, not just structure
4. Unit test file with tests that verify the contract (can test against mock/stub implementations)

Example from This Codebase

# src/services/extraction/base.py
from abc import ABC, abstractmethod

class ExtractionProvider(ABC):
    """Contract for document extraction providers.

    Implementations must handle PDF, DOCX, and TXT formats.
    All methods are thread-safe and may be called concurrently.
    """

    @abstractmethod
    def extract_text(self, file_path: str) -> ExtractionResult:
        """Extract text content from a document.

        Args:
            file_path: Absolute path to the document file.

        Returns:
            ExtractionResult containing:
            - text: The extracted text content
            - metadata: Document metadata dict
            - page_count: Number of pages (1 for non-paginated)

        Raises:
            FileNotFoundError: If file_path does not exist
            UnsupportedFormatError: If file format is not supported
            ExtractionError: If extraction fails for other reasons

        Thread Safety:
            This method is thread-safe and may be called concurrently.
        """
        pass