Skip to content
Skills Library
Programming · Planning

interface-contracts

/interface-contracts

Use when planning a feature where multiple components implement the same boundary, work can be parallelized across agents, or several tasks are blocked by a shared dependency. Defines an abstract base class or Protocol with @abstractmethod decorators, complete type hints, behavior-documenting docstrings, and contract tests; sets up the interface task plus per-implementation tasks with depends_on links so multiple agents can work in parallel. Trigger phrases include 'interface contract', 'parallel implementation', 'shared boundary', 'multi-agent coordination', 'contract-first', 'unblock paralle

Licence
Apache-2.0
Last repository change
17.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.06.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when planning a feature where multiple components implement the same boundary, work can be parallelized across agents, or several tasks are blocked by a shared dependency. Defines an abstract base class or Protocol with @abstractmethod decorators, complete type hints, behavior-documenting docstrings, and contract tests; sets up the interface task plus per-implementation tasks with depends_on links so multiple agents can work in parallel. Trigger phrases include 'interface contract', 'parallel implementation', 'shared boundary', 'multi-agent coordination', 'contract-first', 'unblock paralle

Triggers from the description

interface contractparallel implementationshared boundarymulti-agent coordinationcontract-first
Original author description

Use when planning a feature where multiple components implement the same boundary, work can be parallelized across agents, or several tasks are blocked by a shared dependency. Defines an abstract base class or Protocol with @abstractmethod decorators, complete type hints, behavior-documenting docstrings, and contract tests; sets up the interface task plus per-implementation tasks with depends_on links so multiple agents can work in parallel. Trigger phrases include 'interface contract', 'parallel implementation', 'shared boundary', 'multi-agent coordination', 'contract-first', 'unblock paralle

How it works

  1. When to Create an Interface Contract
  2. Interface Contract Requirements
  3. Parallel Work Pattern
  4. Task Setup
  5. Checklist
  6. Common Pitfalls
  7. Workflow Summary
Original SKILL.md headings · 141 lines, 700 words
SKILL.md preview
---
name: interface-contracts
description: Use when planning a feature where multiple components implement the same boundary, work can be parallelized across agents, or several tasks are blocked by a shared dependency. Defines an abstract base class or Protocol with @abstractmethod decorators, complete type hints, behavior-documenting docstrings, and contract tests; sets up the interface task plus per-implementation tasks with depends_on links so multiple agents can work in parallel. Trigger phrases include 'interface contract', 'parallel implementation', 'shared boundary', 'multi-agent coordination', 'contract-first', 'unblock parallel work', 'define an ABC', 'set up a Protocol'.
user-invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# 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

```python
# 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
```

## Parallel Work Pattern

```
Pattern: Main Agent → Create interface contract (ABC, tests, docs)
         → Interface complete
         → [parallel] Impl Agent 1: Provider A | Impl Agent 2: Provider B
         → Both complete → Integration ready
```

## Task Setup

```bash
# 1. Create interface task (unblocks others)
.claude/scripts/dso ticket create task "Define MyProvider interface contract" --priority 1 -d "Define the abstract base class for MyProvider: method signatures, expected behavior, error contracts."
# Returns: <issue-id>

# 2. Create implementation tasks
.claude/scripts/dso ticket create task "Implement ConcreteProviderA" --priority 2 -d "Implement MyProvider interface for ConcreteProviderA. Must satisfy all contracts from <issue-id>."
.claude/scripts/dso ticket create task "Implement ConcreteProviderB" --priority 2 -d "Implement MyProvider interface for ConcreteProviderB. Must satisfy all contracts from <issue-id>."
# Returns: <issue-id-a>, <issue-id-b>

# 3. Set dependencies
.claude/scripts/dso ticket link <issue-id-a> <issue-id> depends_on
.claude/scripts/dso ticket link <issue-id-b> <issue-id> depends_on

# 4. Document interface after completion
.claude/scripts/dso ticket comment <issue-id> "Interface: src/services/domain/base.py
Key methods: process(), validate()
Constraint: All implementations thread-safe"
```

### Documenting Interface Contracts for Other Agents

When you complete an interface contract task, ensure:

1. **The interface file exists** with all abstract methods decorated
2. **Tests exist** that verify the contract (even if they test stubs)
3. **The ticket issue notes** include:
   - Path to the interface file
   - Key methods and their purposes
   - Any non-obvious constraints or invariants

## Checklist

Before marking an interface contract task complete:

- [ ] ABC/Protocol with `@abstractmethod` decorators
- [ ] Complete type hints on all methods
- [ ] Docstrings document behavior + exceptions + thread safety
- [ ] Test file with contract verification tests
- [ ] Lint (type-check) passes: `LINT_CMD=$(.claude/scripts/dso read-config commands.lint) && $LINT_CMD`
- [ ] Ticket notes include file path and constraints

## Common Pitfalls

| Pitfall | Problem | Solution |
|---------|---------|----------|
| Forgetting `@abstractmethod` | Subclasses can skip implementation | Always decorate abstract methods |
| Missing return type hints | MyPy can't verify implementations match | Use `-> ReturnType` on all methods |
| No docstring on abstract method | Contract is unclear to implementers | Document expected behavior fully |
| Not running mypy after changes | Type errors slip through to CI | Run `LINT_CMD=$(.claude/scripts/dso read-config commands.lint) && $LINT_CMD` after changes |

## Workflow Summary

```bash
# 1. Create the abstract base class with @abstractmethod decorators
# 2. Write comprehensive docstrings
# 3. Create concrete implementation(s)
# 4. Write tests for base class and implementations
# 5. Run type checking - REQUIRED
LINT_CMD=$(.claude/scripts/dso read-config commands.lint) && $LINT_CMD  # Must pass

# 6. Run validation
.claude/scripts/dso validate.sh --ci

# 7. Commit using the project commit workflow (CLAUDE.md `rule:raw-commit`)
# Use /dso:commit or follow COMMIT-WORKFLOW.md — never raw git commit
```

Versions

The database has no other skills named interface-contracts.

Database snapshot: 13.11.2026 · package version 813c5c994a06 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100module-component-generator
    Generates complete modules and components from interface contracts and specifications. Use when Claude needs to build larger software components, implement interfaces, create service layers, or generate complete modules with multiple related classes. Supports Python (with type…
  • 100parallel-feature-development
    Coordinate parallel feature development with file ownership strategies, conflict avoidance rules, and integration patterns for multi-agent implementation. Use this skill when decomposing a large feature into independent work streams, when two or more agents need to implement…
  • 100design-it-twice
    Generate multiple radically different interface designs for a module using parallel sub-agents, then compare and synthesize. Based on Ousterhout's "Design It Twice" principle. Use when the user wants to explore interface options, design an API, compare module shapes, or says…
  • 100api-contract
    Configure this skill should be used when the user asks about "API contract", "api-contract.md", "shared interface", "TypeScript interfaces", "request response schemas", "endpoint design", or needs guidance on designing contracts that coordinate backend and frontend agents. Use…
  • 100test-contract
    Generate protocol/interface test suites that any implementation must pass. Define the contract once, test every implementation. Use when designing protocols or swapping implementations.
  • 100parallel-yak-implementation
    Use when multiple independent leaf yaks are ready to implement and can be worked on concurrently with separate agents in worktrees

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.