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
- Author
- navapbc ↗
- Repository
- digital-service-orchestra ↗
- Licence
- Apache-2.0
- Last repository change
- 17.06.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.06.2026, without references to retired models or APIs.
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
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
- When to Create an Interface Contract
- Interface Contract Requirements
- Parallel Work Pattern
- Task Setup
- Checklist
- Common Pitfalls
- Workflow Summary
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